Saxon.Api

 

 

Saxon.Api

Class XPathCompiler

public class XPathCompiler

An XPathCompiler object allows XPath queries to be compiled. The compiler holds information that represents the static context for the expression.

To construct an XPathCompiler, use the factory method NewXPathCompiler on the XPathCompiler.Processor object.

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

The XPathCompiler has the ability to maintain a cache of compiled expressions. This is active only if enabled by setting the Caching property. If caching is enabled, then the compiler will recognize an attempt to compile the same expression twice, and will avoid the cost of recompiling it. The cache is emptied by any method that changes the static context for subsequent expressions, for example, by setting the BaseUri property. Unless the cache is emptied, it grows indefinitely: compiled expressions are never discarded.

Property Summary
 bool AllowUndeclaredVariables

This property indicates whether the XPath expression may contain references to variables that have not been explicitly declared by calling DeclareVariable. The property is false by default (that is, variables must be declared).

 bool BackwardsCompatible

XPath 1.0 Backwards Compatibility Mode (that is, XPath 1.0 compatibility mode). If true, backwards compatibility mode is set. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).

 Uri BaseUri

The base URI of the expression, which forms part of the static context of the expression. This is used for resolving any relative URIs appearing within the expression, for example in the argument to the doc() function.

 bool Caching

This property controls caching of compiled XPath expressions. If caching is enabled, then compiled expressions are saved in a cache and reused if the same expression is compiled again. The cache is cleared (invalidated) if any change is made to the properties of the XPathCompiler that would affect the validity of cached expressions. Caching is disabled by default.

 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.

 bool FastCompilation

Request 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 expression is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

 Processor Processor

The Processor from which this XPathCompiler was constructed

 bool SchemaAware

This property indicates whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the method XPathCompiler.ImportSchemaNamespace(String) is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.

 UnprefixedElementMatchingPolicy UnprefixedElementMatchingPolicy

The policy for matching unprefixed element names in XPath expressions

 ErrorReporter WarningHandler

Set the error reporter to be used for reporting static warnings during compilation. By default, the ErrorReporter associated with the Saxon Configuration is used. Note that fatal static errors are always reported in the form of an exception thrown by the XPathCompiler.Compile(String) method, so this method only controls the handling of warnings

 string XPathLanguageVersion

This property indicates which version of XPath language syntax is accepted. The accepted values are "2.0", "3.0", "3.1", and "4.0". The default is "3.1".

 

Method Summary
 void AddXsltFunctionLibrary (XsltPackage libraryPackage)

Make available a set of functions defined in an XSLT 3.0 package. All functions defined with visibility="public" (or exposed as public using xsl:expose become part of the static context for an XPath expression created using this XPathCompiler. The functions are added to the search path after all existing functions, including functions added using a previous call on this method.

Note that if the library package includes functions that reference stylesheet parameters (or global variables that depend on the context item), then there is no way of supplying values for such parameters; calling such functions will cause a run-time error.
 XPathExecutable Compile (string source)

Compile an expression supplied as a String.

 void DeclareDefaultCollation (string uri)

Declare the default collation

 void DeclareNamespace (string prefix, string uri)

Declare a namespace for use by the XPath expression.

 void DeclareVariable (QName name)

Declare a variable for use by the XPath expression. If the expression refers to any variables, then they must be declared here, unless the AllowUndeclaredVariables property has been set to true.

 XdmValue Evaluate (string expression, XdmItem contextItem)

Compile and execute an expression supplied as a String, with a given context item.

 XdmItem EvaluateSingle (string expression, XdmItem contextItem)

Compile and execute an expression supplied as a String, with a given context item, where the expression is expected to return a single item as its result.

 string GetNamespaceURI (string lexicalName, bool useDefault)

Get the namespace URI part of a QName provided in lexical form (prefix:localName)

 void ImportSchemaNamespace (string uri)

Import schema definitions for a specified namespace. That is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

 void SetDecimalFormatProperty (QName format, string property, string value)

Sets a property of a selected decimal format, for use by the format-number() function.

 

Property Detail

AllowUndeclaredVariables

public bool AllowUndeclaredVariables {get; set; }

This property indicates whether the XPath expression may contain references to variables that have not been explicitly declared by calling DeclareVariable. The property is false by default (that is, variables must be declared).

If undeclared variables are permitted, then it is possible to determine after compiling the expression which variables it refers to by calling the method EnumerateExternalVariables on the XPathExecutable object.

BackwardsCompatible

public bool BackwardsCompatible {get; set; }

XPath 1.0 Backwards Compatibility Mode (that is, XPath 1.0 compatibility mode). If true, backwards compatibility mode is set. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).

Setting XPath 1.0 compatibility mode does not prevent the use of constructs defined in a later XPath version; rather, it modifies the semantics of some constructs.

BaseUri

public Uri BaseUri {get; set; }

The base URI of the expression, which forms part of the static context of the expression. This is used for resolving any relative URIs appearing within the expression, for example in the argument to the doc() function.

Caching

public bool Caching {get; set; }

This property controls caching of compiled XPath expressions. If caching is enabled, then compiled expressions are saved in a cache and reused if the same expression is compiled again. The cache is cleared (invalidated) if any change is made to the properties of the XPathCompiler that would affect the validity of cached expressions. Caching is disabled by default.

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.

FastCompilation

public bool FastCompilation {get; set; }

Request 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 expression is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

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; }

The Processor from which this XPathCompiler was constructed

SchemaAware

public bool SchemaAware {get; set; }

This property indicates whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the method XPathCompiler.ImportSchemaNamespace(String) is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.

UnprefixedElementMatchingPolicy

public UnprefixedElementMatchingPolicy UnprefixedElementMatchingPolicy {get; set; }

The policy for matching unprefixed element names in XPath expressions

WarningHandler

public ErrorReporter WarningHandler {set; }

Set the error reporter to be used for reporting static warnings during compilation. By default, the ErrorReporter associated with the Saxon Configuration is used. Note that fatal static errors are always reported in the form of an exception thrown by the XPathCompiler.Compile(String) method, so this method only controls the handling of warnings

The property IErrorReporter to which warnings will be notified

XPathLanguageVersion

public string XPathLanguageVersion {get; set; }

This property indicates which version of XPath language syntax is accepted. The accepted values are "2.0", "3.0", "3.1", and "4.0". The default is "3.1".

Requesting a value lower than 3.1 restricts the XPath grammar to constructs defined in the appropriate version, and uses the appropriate subsets of the functions in the standard function library. However, the semantics of remaining constructs will generally follow the XPath 3.1 rules. For example, there is a rule in XPath 2.0 that casting to xs:QName is only permitted if the operand is a string literal, but this is not enforced when this property is set to "2.0".

There is no support for XPath 1.0.

The value "4.0" enables use of XPath 4.0 syntax. XPath 4.0 is work in progress, and the specification is far from stable.

Method Detail

AddXsltFunctionLibrary

public void AddXsltFunctionLibrary(XsltPackage libraryPackage)

Make available a set of functions defined in an XSLT 3.0 package. All functions defined with visibility="public" (or exposed as public using xsl:expose become part of the static context for an XPath expression created using this XPathCompiler. The functions are added to the search path after all existing functions, including functions added using a previous call on this method.

Note that if the library package includes functions that reference stylesheet parameters (or global variables that depend on the context item), then there is no way of supplying values for such parameters; calling such functions will cause a run-time error.

Parameters:

libraryPackage - the XSLT compiled library package whose functions are to be made available

Compile

public XPathExecutable Compile(string source)
throws
SaxonApiException

Compile an expression supplied as a String.

Parameters:

source - A string containing the source text of the XPath expression

Returns:

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

Throws:

SaxonApiException -  Throws a Saxon.Api.SaxonApiException if there is any static error in the expression (for example, a syntax error, or a reference to an undeclared function or variable).

Example:

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

DeclareDefaultCollation

public void DeclareDefaultCollation(string uri)

Declare the default collation

Parameters:

uri - the absolute URI of the default collation. This URI must identify a known collation; either one that has been explicitly declared, or one that is recognized implicitly, such as a UCA collation

DeclareNamespace

public void DeclareNamespace(string prefix,
string uri)

Declare a namespace for use by the XPath expression.

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.

DeclareVariable

public void DeclareVariable(QName name)

Declare a variable for use by the XPath expression. If the expression refers to any variables, then they must be declared here, unless the AllowUndeclaredVariables property has been set to true.

Parameters:

name - The name of the variable, as a QName

Evaluate

public XdmValue Evaluate(string expression,
XdmItem contextItem)
throws
SaxonApiException

Compile and execute an expression supplied as a String, with a given context item.

Parameters:

expression - A string containing the source text of the XPath expression
contextItem - The context item to be used for evaluation of the XPath expression. May be null, in which case the expression is evaluated without any context item.

Returns:

An XdmValue which is the result of evaluating the XPath expression.

Throws:

SaxonApiException -  Throws a Saxon.Api.SaxonApiException if there is any static error in the expression (for example, a syntax error, or a reference to an undeclared function or variable), or if a dynamic error during its evaluation (for example, referring to the context item if no context item was supplied.)

EvaluateSingle

public XdmItem EvaluateSingle(string expression,
XdmItem contextItem)
throws
SaxonApiException

Compile and execute an expression supplied as a String, with a given context item, where the expression is expected to return a single item as its result.

Parameters:

expression - A string containing the source text of the XPath expression
contextItem - The context item to be used for evaluation of the XPath expression. May be null, in which case the expression is evaluated without any context item.

Returns:

If the XPath expression returns a singleton, then the the XdmItem which is the result of evaluating the XPath expression. If the expression returns an empty sequence, then null. If the expression returns a sequence containing more than one item, then the first item in the result.

Throws:

SaxonApiException -  Throws a Saxon.Api.SaxonApiException if there is any static error in the expression (for example, a syntax error, or a reference to an undeclared function or variable), or if a dynamic error during its evaluation (for example, referring to the context item if no context item was supplied.)

GetNamespaceURI

public string GetNamespaceURI(string lexicalName,
bool useDefault)

Get the namespace URI part of a QName provided in lexical form (prefix:localName)

Parameters:

lexicalName - The lexical QName. This may either be a plain NCName (a local name with no prefix or colon) or a lexical name using a prefix that is bound to a namespace.
useDefault - Set to true if the default namespace for elements and types is to be used in the case where there is no prefix. If false, no prefix means no namespace.

Returns:

The namespace URI associated with the prefix (or absence thereof) in the supplied lexical QName. The "null namespace" is represented by a zero length string. The method returns null if there is no known binding for the prefix used in the lexical QName.

ImportSchemaNamespace

public void ImportSchemaNamespace(string uri)

Import schema definitions for a specified namespace. That is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

This method will not cause the schema to be loaded. That must be done separately, using the SchemaManager. This method will not fail if the schema has not been loaded (but in that case the set of declarations and definitions made available to the XPath expression is empty). The schema document for the specified namespace may be loaded before or after this method is called.

This method does not bind a prefix to the namespace. That must be done separately, using the DeclareNamespace method.

Parameters:

uri - The namespace URI whose declarations and type definitions are to be made available for use within the XPath expression.

SetDecimalFormatProperty

public void SetDecimalFormatProperty(QName format,
string property,
string value)

Sets a property of a selected decimal format, for use by the format-number() function.

This method checks that the value is valid for the particular property, but it does not check that all the values for the decimal format are consistent (for example, that the decimal separator and grouping separator have different values). This consistency check is performed only when the decimal format is used.

Parameters:

format - The name of the decimal format whose property is to be set. Supply null to set a property of the default (unnamed) decimal format. This corresponds to a name used in the third argument of format-number().
property - The name of the property to set: one of "decimal-separator", "grouping-separator", "infinity", "NaN", "minus-sign", "percent", "per-mille", "zero-digit", "digit", or "pattern-separator".
value - The new value for the property.