Saxon.Api

 

 

Saxon.Api

Class XPathSelector

public class XPathSelector
implements IEnumerable

An XPathSelector represents a compiled and loaded XPath expression ready for execution. The XPathSelector holds details of the dynamic evaluation context for the XPath expression.

An XPathSelector should not be used concurrently in multiple threads. It is safe, however, to reuse the object within a single thread to evaluate the same XPath expression several times. Evaluating the expression does not change the context that has been established.

An XPathSelector is always constructed by running the Load method of an XPathExecutable.

The class XPathSelector implements IEnumerable, so it is possible to enumerate the results in a for expression.

Property Summary
 XdmItem ContextItem

The context item for the XPath expression evaluation.

 net.sf.saxon.sxpath.XPathDynamicContext Implementation

Escape hatch to the Saxon.Hej.s9api.XPathSelector object in the underlying Java implementation

 ResourceResolver TextResolver

The TextResolver to be used at run-time to resolve and dereference URIs supplied to the unparsed-text(), unparsed-text-lines(), unparsed-text-available(), and json-doc() functions.

 ResourceResolver XmlDocumentResolver

The ResourceResolver to be used at run-time to resolve and dereference URIs supplied to the fn:doc() and fn:doc-available() functions, and also fn:transform.

 

Method Summary
 bool EffectiveBooleanValue ()

Evaluate the effective boolean value of the XPath expression, returning the result as a Boolean

 XdmValue Evaluate ()

Evaluate the expression, returning the result as an XdmValue (that is, a sequence of nodes, atomic values, and possibly function items such as maps and arrays).

 XdmItem EvaluateSingle ()

Evaluate the XPath expression, returning the result as an XdmItem (that is, a single node or atomic value).

 IEnumerator GetEnumerator ()

Evaluate the expression, returning the result as an IEnumerator (that is, an enumerator over a sequence of nodes and/or atomic values).

 void SetVariable (QName name, XdmValue value)

Set the value of a variable

 

Property Detail

ContextItem

public XdmItem ContextItem {get; set; }

The context item for the XPath expression evaluation.

This may be either a node or an atomic value. Most commonly it will be a document node, which might be constructed using the Build method of the DocumentBuilder object.

Implementation

public net.sf.saxon.sxpath.XPathDynamicContext Implementation {get; }

Escape hatch to the Saxon.Hej.s9api.XPathSelector object in the underlying Java implementation

TextResolver

public ResourceResolver TextResolver {get; set; }

The TextResolver to be used at run-time to resolve and dereference URIs supplied to the unparsed-text(), unparsed-text-lines(), unparsed-text-available(), and json-doc() functions.

If no TextResolver is supplied, or if the supplied TextResolver returns null when called, the CommonResourceResolver for the Saxon Configuration is invoked, with a ResourceRequest having Nature == ResourceRequest.TEXT_NATURE. If this returns null, then the "direct" URI resolution provided by Org.XmlResolver.UriUtils is invoked: this is capable of handling regular file:, http:, and https: URIs, as well as the data: and pack: schemes.

If the call on unparsed-text() supplies an encoding parameter, this is made available in the call to the TextResolver.

XmlDocumentResolver

public ResourceResolver XmlDocumentResolver {get; set; }

The ResourceResolver to be used at run-time to resolve and dereference URIs supplied to the fn:doc() and fn:doc-available() functions, and also fn:transform.

The URI supplied as the first argument to the resolver is the absolute URI requested, that is, the result of resolving the requested relative URI against the relevant base URI.

The requested relative URI and the corresponding base URI are supplied as separate properties within the ResourceProperties argument, in case they are needed.

The returned IResource must be one of the following:

  • An IResource such as a NodeResource or an XmlReaderResource whose getItem() method delivers an XdmNode;
  • A TextResource delivering lexical XML in its Content property; this will then be parsed to deliver the corresponding XML document.

If no XmlDocumentResolver is supplied, or if it returns null, then the CommonResourceResolver associated with the Saxon Configuration is invoked; if this also returns null, then the URI is resolved directly.

Method Detail

EffectiveBooleanValue

public bool EffectiveBooleanValue()
throws
SaxonApiException

Evaluate the effective boolean value of the XPath expression, returning the result as a Boolean

Returns:

A Boolean representing the result of the expression, converted to its effective boolean value as if by applying the XPath boolean() function

Throws:

SaxonApiException -  Throws Saxon.Api.DynamicError if the evaluation of the XPath expression fails with a dynamic error.

Evaluate

public XdmValue Evaluate()
throws
SaxonApiException

Evaluate the expression, returning the result as an XdmValue (that is, a sequence of nodes, atomic values, and possibly function items such as maps and arrays).

Although a singleton result may be represented as an XdmItem, there is no guarantee that this will always be the case. If you know that the expression will return at most one node or atomic value, it is best to use the EvaluateSingle method, which does guarantee that an XdmItem (or null) will be returned.

Returns:

An XdmValue representing the results of the expression.

Throws:

SaxonApiException -  Throws Saxon.Api.SaxonApiException if the evaluation of the XPath expression fails with a dynamic error.

EvaluateSingle

public XdmItem EvaluateSingle()
throws
SaxonApiException

Evaluate the XPath expression, returning the result as an XdmItem (that is, a single node or atomic value).

Returns:

An XdmItem representing the result of the expression, or null if the expression returns an empty sequence. If the expression returns a sequence of more than one item, any items after the first are ignored.

Throws:

SaxonApiException -  Throws Saxon.Api.DynamicError if the evaluation of the XPath expression fails with a dynamic error.

GetEnumerator

public IEnumerator GetEnumerator()
throws
SaxonApiException

Evaluate the expression, returning the result as an IEnumerator (that is, an enumerator over a sequence of nodes and/or atomic values).

Returns:

An enumerator over the sequence that represents the results of the expression. Each object in this sequence will be an instance of XdmItem. Note that the expression may be evaluated lazily, which means that a successful response from this method does not imply that the expression has executed successfully: failures may be reported later while retrieving items from the iterator.

Throws:

SaxonApiException -  May throw a Saxon.Api.DynamicError if the evaluation of the XPath expression fails with a dynamic error. However, some errors will not be detected during the invocation of this method, but only when stepping through the returned SequenceEnumerator.

SetVariable

public void SetVariable(QName name,
XdmValue value)

Set the value of a variable

Parameters:

name - The name of the variable. This must match the name of a variable that was declared to the XPathCompiler. No error occurs if the expression does not actually reference a variable with this name.
value - The value to be given to the variable.