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 XPathCompiler 

public class XPathCompiler
implements object

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

Get the Processor from which this XPathCompiler was constructed

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

 Boolean SchemaAware

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

 string XPathLanguageVersion

This property indicates which version of XPath language syntax is accepted. The default value is "1.0". This property must be set to "3.0" before compiling a query that uses XPath 3.0 (formerly known as XPath 2.1) syntax.

 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 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 references to library modules, schema locations, or as an argument to the doc() function.

 Boolean BackwardsCompatible

XPath 1.0 Backwards 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).

 Boolean Caching

XPath 1.0 Backwards 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).

 
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

 void DeclareNamespace(string prefix, string uri)

Declare a namespace for use by the XPath expression.

 string GetNamespaceURI(string lexicalName, Boolean useDefault)
 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.

 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.

 XPathExecutable Compile(string source)

Compile an expression supplied as a String.

 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

 
Property Detail

Processor

public Processor Processor {get; set; }

Get the Processor from which this XPathCompiler was constructed

AllowUndeclaredVariables

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

SchemaAware

public Boolean SchemaAware {get; set; }

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

XPathLanguageVersion

public string XPathLanguageVersion {get; set; }

This property indicates which version of XPath language syntax is accepted. The default value is "1.0". This property must be set to "3.0" before compiling a query that uses XPath 3.0 (formerly known as XPath 2.1) syntax.

Support for XPath 3.0 is currently limited: for details see the Saxon documentation.

Property added in Saxon 9.4

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.

BaseUri

public String 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 references to library modules, schema locations, or as an argument to the doc() function.

BackwardsCompatible

public Boolean BackwardsCompatible {get; set; }

XPath 1.0 Backwards 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).

Caching

public Boolean Caching {get; set; }

XPath 1.0 Backwards 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).

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

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.

GetNamespaceURI

public string GetNamespaceURI(string lexicalName,
Boolean useDefault)

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

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

Compile

public XPathExecutable Compile(string source)
throws
Saxon.Api.StaticError

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:
Saxon.Api.StaticError - Throws a Saxon.Api.StaticError if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.

Evaluate

public XdmValue Evaluate(string expression,
XdmItem contextItem)
throws
Saxon.Api.StaticError,
Saxon.Api.DynamicError

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:
Saxon.Api.StaticError - Throws a Saxon.Api.StaticError if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.
Saxon.Api.DynamicError - Throws a Saxon.Api.DynamicError if there is any dynamic error during evaluation of the XPath expression. This includes, for example, referring to the context item if no context item was supplied.

EvaluateSingle

public XdmItem EvaluateSingle(string expression,
XdmItem contextItem)
throws
Saxon.Api.StaticError,
Saxon.Api.DynamicError

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:
Saxon.Api.StaticError - Throws a Saxon.Api.StaticError if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.
Saxon.Api.DynamicError - Throws a Saxon.Api.DynamicError if there is any dynamic error during evaluation of the XPath expression. This includes, for example, referring to the context item if no context item was supplied.