Saxon.Api

 

 

Saxon.Api

Class XQueryCompiler

public class XQueryCompiler

The XQueryCompiler object allows XQuery queries to be compiled.

To construct an XQueryCompiler, use the factory method NewXQueryCompiler on the XQueryCompiler.Processor object.

The XQueryCompiler holds information that represents the static context for the queries that it compiles. This information remains intact after performing a compilation. An XQueryCompiler may therefore be used repeatedly to compile multiple queries. Any changes made to the XQueryCompiler (that is, to the static context) do not affect queries that have already been compiled.

An XQueryCompiler 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 query, which forms part of the static context of the query. This is used for resolving any relative URIs appearing within the query, for example in references to library modules, schema locations, or as an argument to the doc() function.

 bool CompileWithTracing

Property indicating that the query is to be compiled with tracing enabled.

 XdmItemType ContextItemType

The required context item type for the expression. This is used for optimizing the expression at compile time, and to check at run-time that the value supplied for the context item is the correct type.

 string DefaultCollationName

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

 ErrorReporter ErrorReporter

Set the ErrorReporter to be used when validating instance documents as a user defined IErrorReporter. Requirements here is IErrorReport implementation with a user-written report() method, it is possible to intercept error conditions as they occur. If this property is used then the ErrorList property and SetErrorList method is overriden.
 bool FastCompilation

Property indicating that fast compilation is preferred. 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 expression is known to be correct, and (b) once compiled, the expression is only executed once against a document of modest size.

 Processor Processor

Get the Processor from which this XQueryCompiler was constructed

 bool SchemaAware

Property indicating that the query is to be compiled to be schema-aware, even if it contains no "import schema" declarations. Normally a query is treated as schema-aware only if it contains one or more "import schema" declarations.

 bool StreamingEnabled

Property indicating that the query is to be compiled to enable streaming, which is necessary if the query is to be executed using the method XQueryEvaluator.RunStreamed(). In streaming mode, the source document is supplied as a stream, and no tree is built in memory. The default is false.

 bool UpdatingEnabled

This property indicates whether XQuery Update syntax is accepted. The default value is false. This property must be set to true before compiling a query that uses update syntax.

 string XQueryLanguageVersion

This property indicates which version of XQuery language syntax is accepted. The values accepted are "3.1" and "4.0". The default is "3.1".

 XQueryResolver XQueryResolver

A user-supplied XQueryResolver used to resolve the URIs appearing in an import module declaration.

 

Method Summary
 XQueryExecutable Compile (Stream query)

Compile a query supplied as a Stream.

 XQueryExecutable Compile (string query)

Compile a query supplied as a string.

 void CompileLibrary (Stream query)

Compile a library module supplied as a stream. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

 void CompileLibrary (string query)

Compile a library module supplied as a string. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

 void DeclareNamespace (string prefix, string uri)

Declare a namespace for use by the query. This has the same status as a namespace declaration appearing within the query prolog (though a declaration of the same prefix in the query prolog will take precedence).

 

Property Detail

BaseUri

public Uri BaseUri {get; set; }

The base URI of the query, which forms part of the static context of the query. This is used for resolving any relative URIs appearing within the query, for example in references to library modules, schema locations, or as an argument to the doc() function.

CompileWithTracing

public bool CompileWithTracing {get; set; }

Property indicating that the query is to be compiled with tracing enabled.

This allows tracing to be switched on at run-time, but it has no effect unless run-time tracing is activated.

ContextItemType

public XdmItemType ContextItemType {get; set; }

The required context item type for the expression. This is used for optimizing the expression at compile time, and to check at run-time that the value supplied for the context item is the correct type.

DefaultCollationName

public string DefaultCollationName {get; set; }

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

ErrorReporter

public ErrorReporter ErrorReporter {get; set; }

Set the ErrorReporter to be used when validating instance documents as a user defined IErrorReporter. Requirements here is IErrorReport implementation with a user-written report() method, it is possible to intercept error conditions as they occur. If this property is used then the ErrorList property and SetErrorList method is overriden.

The IErrorReporter to be used

FastCompilation

public bool FastCompilation {get; set; }

Property indicating that fast compilation is preferred. 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 expression is known to be correct, and (b) once compiled, the expression is only executed once against a document of modest size.

The current implementation is equivalent to switching off all optimizations. 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.

Processor

public Processor Processor {get; }

Get the Processor from which this XQueryCompiler was constructed

SchemaAware

public bool SchemaAware {get; set; }

Property indicating that the query is to be compiled to be schema-aware, even if it contains no "import schema" declarations. Normally a query is treated as schema-aware only if it contains one or more "import schema" declarations.

If the query is not schema-aware, then all input documents must be untyped (or xs:anyType), and validation of temporary nodes is disallowed (though validation of the final result tree is permitted). Setting the argument to true means that schema-aware code will be compiled regardless.

StreamingEnabled

public bool StreamingEnabled {get; set; }

Property indicating that the query is to be compiled to enable streaming, which is necessary if the query is to be executed using the method XQueryEvaluator.RunStreamed(). In streaming mode, the source document is supplied as a stream, and no tree is built in memory. The default is false.

When the value is set to true, this has the additional side-effect of setting the required context item type to document-node().

UpdatingEnabled

public bool UpdatingEnabled {get; set; }

This property indicates whether XQuery Update syntax is accepted. The default value is false. This property must be set to true before compiling a query that uses update syntax.

This property must be set to true before any query can be compiled that uses updating syntax. This applies even if the query is not actually an updating query (for example, a copy-modify expression). XQuery Update syntax is accepted only by Saxon-EE. Non-updating queries are accepted regardless of the value of this property.

XQueryLanguageVersion

public string XQueryLanguageVersion {get; set; }

This property indicates which version of XQuery language syntax is accepted. The values accepted are "3.1" and "4.0". The default is "3.1".

XQuery 4.0 is work in progress, and the specification is far from stable.

XQueryResolver

public XQueryResolver XQueryResolver {get; set; }

A user-supplied XQueryResolver used to resolve the URIs appearing in an import module declaration.

If an import module declaration identifies a module URI that has already been loaded, then the existing module is used (regardless of location hints and regardless of the XQueryResolver), unless the configuration option XQUERY_MULTIPLE_MODULE_IMPORTS is set. If this option is set, then an existing module will be reused if the location hint matches; otherwise a new module is loaded (which can potentially cause a failure if it results in duplicate variables or functions having the same name).

The XQueryResolver can return multiple library modules; if it does so, they are all imported. If it returns an empty array, nothing is imported.

If the XQueryResolver returns null (as distinct from returning an empty array), then the import module declaration is resolved as if there were no user-supplied XQueryResolver.

If there is no user-supplied XQueryResolver, and if the module has not already been loaded, then an import module declaration is interpreted as follows. First, if there are no location hints, then a static error is reported. Otherwise, each URI listed in the location hints is resolved using the default resolution algorithm for the Processor, and this is expected to deliver an input stream containing an XQuery library module.

The interface changed in Saxon 11.1 so that the XQueryResolver now returns one or more TextResource objects. The previous class XQueryModuleSource no longer exists.

Method Detail

Compile

public XQueryExecutable Compile(Stream query)
throws
SaxonApiException

Compile a query supplied as a Stream.

The XQuery processor attempts to deduce the encoding of the query by looking for a byte-order-mark, or if none is present, by looking for the encoding declaration in the XQuery version declaration. For this to work, the stream must have the CanSeek property. If no encoding information is present, UTF-8 is assumed.

The base URI of the query is set to the value of the BaseUri property. If this has not been set, then the base URI will be undefined, which means that any use of an expression that depends on the base URI will cause an error.

Parameters:

query - A stream containing the source text of the query

Returns:

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

Throws:

SaxonApiException - Throws a SaxonApiException if errors were detected during static analysis of the query. 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:

XQueryExecutable q = compiler.Compile(new FileStream("input.xq", FileMode.Open, FileAccess.Read));

Compile

public XQueryExecutable Compile(string query)
throws
SaxonApiException

Compile a query supplied as a string.

Using this method the query processor is provided with a string of Unicode characters, so no decoding is necessary. Any encoding information present in the version declaration is therefore ignored.

Parameters:

query - A string containing the source text of the query

Returns:

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

Throws:

SaxonApiException - Throws a SaxonApiException if errors were detected during static analysis of the query. 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:

XQueryExecutable q = compiler.Compile("distinct-values(//*/node-name()");

CompileLibrary

public void CompileLibrary(Stream query)
throws

Compile a library module supplied as a stream. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

The base URI of the query should be supplied by setting the BaseURI property of the QueryCompiler.

Parameters:

query - A stream delivering the text of the query

Throws:

 - SaxonApiException if the query compilation fails with a static error

CompileLibrary

public void CompileLibrary(string query)
throws

Compile a library module supplied as a string. The code generated by compiling the library is available for importing by all subsequent compilations using the same XQueryCompiler; it is identified by an "import module" declaration that specifies the module URI of the library module. No module location hint is required, and if one is present, it is ignored.

The base URI of the query should be supplied by setting the BaseURI property of the QueryCompiler.

Parameters:

query - The text of the query

Throws:

 - SaxonApiException if the query compilation fails with a static error

DeclareNamespace

public void DeclareNamespace(string prefix,
string uri)

Declare a namespace for use by the query. This has the same status as a namespace declaration appearing within the query prolog (though a declaration of the same prefix in the query prolog will take precedence).

Parameters:

prefix - The namespace prefix to be declared. Use a zero-length string to declare the default namespace (that is, the default namespace for elements and types).
uri - The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace.