#include <DbXml.hpp>

void XmlQueryContext::setReturnType(ReturnType type);
ReturnType XmlQueryContext::getReturnType();

Description: XmlQueryContext::setReturnType

The XmlQueryContext::setReturnType method allows the application to define whether the query should return documents, or values, or both.

The ResultDocuments return type instructs the query processor to select documents from the container that match the query expression. A document is said to match the query if the execution of the query over the document would return a value for that document. The query returns an XmlResults object that contains a list of XmlValues of type XmlValue::DOCUMENT.

The ResultValues return type instructs the query processor to select documents from the container that match the query expression, and to return the result of executing the query over the document. The query returns an XmlResults object that contains a list of XmlValues of type UNREF==XmlValue_NODE. The XmlValues contain deep copies of the result nodes, meaning that all descendant child nodes are also copied. The underlying DOMNodeList or DOMNode can be accessed using the XmlValue::asNodeList method or the XmlValue::asAttribute method. Note that the siblings and the parent of the node can not be navigated to via the DOM API. We term these nodes as being 'dead nodes'.

The ResultDocumentsAndValues return type instructs the query processor to return both documents and values. It behaves just as ResultValues does, returning an XmlResults object that contains a list of XmlValues of type UNREF==XmlValue_NODE. The difference being that the containing XmlDocument can be retrieved by calling the XmlValue::asDocument method. The XmlValues contain references to nodes within a DOM of the whole document, so the siblings and parent of the node can be navigated to via the DOM API. We term these nodes as being 'live nodes'.

The CandidateDocuments return type instructs the query processor to return documents that match the query, but only using the available indices. Under normal processing the matching documents returned from the indices are filtered through a query processor that applies the query against the document. For some query expressions the caller might know that the candidate set is equivalent to the result set. For these expressions there is no need to pass the candidate documents through a filter to eliminate false positives. The query processor can identify some query expressions of this nature, but not all. The CandidateDocuments return type allows the client application to do its own false-positive elimination.

Parameters

type

The type parameter specifies which of documents or values to return, and must be set to one of the following values:

XmlQueryContext::ResultDocuments

Return documents that match the XPath expression.

XmlQueryContext::ResultValues

Return nodes from the documents that match the XPath expression.

XmlQueryContext::ResultDocumentsAndValues

Return both the nodes from the documents that match the query expression, and the matching documents.

XmlQueryContext::CandidateDocuments

Return documents that may match the query expression.

Description: XmlQueryContext::getReturnType

Discover the return type defined for this XmlQueryContext.

Returns the return type defined for this XmlQueryContext.

Class