#include <DbXml.hpp>

XmlResults XmlContainer::queryWithXPath(
	DbTxn *txn, XmlQueryExpression &expression, u_int32_t flags=0) const;

XmlResults XmlContainer::queryWithXPath(
	DbTxn *txn, const std::string &query, XmlQueryContext *context=0, u_int32_t flags=0);

Description: XmlContainer::queryWithXPath

The XmlContainer::queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.

In this case the expression is provided as a string.

The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

Parameters

txn

If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv::txn_begin, otherwise, NULL.

query

The XPath expression is provided as a string and must conform to the syntax defined in the W3C XPath 1.0 specification.

context

The context within which the query is to be performed. The context contains the variable bindings, the namespace prefix to URI mapping, and the query processing flags.

flags

The flags parameter must be set to zero or one of the following values:

DB_DIRTY_READ

Read modified but not yet committed data. Silently ignored if the DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

DB_RMW

Acquire write locks instead of read locks when doing the retrieval. Setting this flag can eliminate deadlock during a read-modify-write cycle by acquiring the write lock during the read part of the cycle so that another thread of control acquiring a read lock for the same item, in its own read-modify-write cycle, will not result in deadlock.

Because the XmlContainer::getDocument method will not hold locks across Berkeley DB interface calls in non-transactional environments, passing the DB_RMW flag to the XmlContainer::getDocument method is meaningful only in the presence of transactions.

Errors

The XmlContainer::queryWithXPath method may fail and throw XmlException, encapsulating one of the following non-zero errors:

CONTAINER_CLOSED

The container is closed.

DATABASE_ERROR

An error occurred in an underlying Berkeley DB database. The XmlException::getDbError method will return the error code for the error.

DOM_PARSER_ERROR

The DOM parser was unable to parse an XML document.

NO_VARIABLE_BINDING

The XPath expression referred to an undefined variable.

XPATH_EVALUATION_ERROR

The XPath evaluator was unable to execute the XPath expression.

XPATH_PARSER_ERROR

The XPath parser could not parse the XPath expression.

Description: XmlContainer::queryWithXPath

The XmlContainer::queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.

In this case the expression is provided in the form of an XmlQueryExpression object. This is a pre-parsed XPath expression created by a call to the XmlContainer::parseXPathExpression method.

The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

Parameters

txn

If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv::txn_begin, otherwise, NULL.

query

The query to be performed, expressed as an XmlQueryExpression object.

flags

The flags parameter must be set to zero or one of the following values:

DB_DIRTY_READ

Read modified but not yet committed data. Silently ignored if the DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

DB_RMW

Acquire write locks instead of read locks when doing the retrieval. Setting this flag can eliminate deadlock during a read-modify-write cycle by acquiring the write lock during the read part of the cycle so that another thread of control acquiring a read lock for the same item, in its own read-modify-write cycle, will not result in deadlock.

Because the XmlContainer::getDocument method will not hold locks across Berkeley DB interface calls in non-transactional environments, passing the DB_RMW flag to the XmlContainer::getDocument method is meaningful only in the presence of transactions.

Errors

The XmlContainer::queryWithXPath method may fail and throw XmlException, encapsulating one of the following non-zero errors:

CONTAINER_CLOSED

The container is closed.

DATABASE_ERROR

An error occurred in an underlying Berkeley DB database. The XmlException::getDbError method will return the error code for the error.

DOM_PARSER_ERROR

The DOM parser was unable to parse an XML document.

NO_VARIABLE_BINDING

The XPath expression referred to an undefined variable.

XPATH_EVALUATION_ERROR

The XPath evaluator was unable to execute the XPath expression.

XPATH_PARSER_ERROR

The XPath parser could not parse the XPath expression.

Class