#include <DbXml.hpp>

XmlResults XmlContainer::lookupIndex(XmlQueryContext &context,
    const std::string &uri, const std::string &name,
    const std::string &index, const XmlValue &value = XmlValue(),
    u_int32_t flags = 0)

XmlResults XmlContainer::lookupIndex(XmlTransaction &txn,
    XmlQueryContext &context, const std::string &uri,
    const std::string &name, const std::string &index,
    const XmlValue &value = XmlValue(), u_int32_t flags = 0)

XmlResults XmlContainer::lookupIndex(XmlQueryContext &context,
    const std::string &uri, const std::string &name,
    const std::string &parent_uri, const std::string &parent_name,
    const std::string &index,const XmlValue &value = XmlValue(),
    u_int32_t flags = 0)

XmlResults XmlContainer::lookupIndex(XmlTransaction &txn,
    XmlQueryContext &context, const std::string &uri,
    const std::string &name, const std::string &parent_uri,
    const std::string &parent_name, const std::string &index,
    const XmlValue &value = XmlValue(),u_int32_t flags = 0)

Description: XmlContainer::lookupIndex

NOTE: this interface is deprecated, in favor of using XmlManager::createIndexLookup and XmlIndexLookup::execute.

For a specified index, return all the data referenced by the index's keys, optionally matching a specific value.

Description: XmlResults XmlContainer::lookupIndex(XmlTransaction &txn, XmlQueryContext &context, const std::string &uri, const std::string &name, const std::string &index, const XmlValue &value = XmlValue(), u_int32_t flags = 0)

Return all the targets for which the identified index has keys. By default, entire documents are returned by this method. However, if the container is of type XmlContainer::NodeStorage (the default container type), and if DBXML_INDEX_NODES is set for the container, then this method will return the individual nodes referenced by the index keys.

Note that you cannot use this form of this method to examine edge indices.

Parameters

txn

If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

context

The XmlQueryContext to use for this query.

uri

The namespace of the node to which this index is applied.

name

The name of the node to which this index is applied.

index

Identifies the index for which you want the documents returned. The value supplied here must be a valid index. See XmlIndexSpecification::addIndex for a description of valid index specifications.

value

Provides the value to which equality indices must be equal. This parameter is required when returning documents on equality indices, and it is ignored for all other types of indices.

flags

The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

DBXML_CACHE_DOCUMENTS

Enables use of a cache mechanism that optimizes XmlIndexLookup::execute operations that a large number of nodes from the same document.

DBXML_LAZY_DOCS

Retrieve the document lazily. That is, retrieve document content and document metadata only on an as needed basis when reading the document.

DB_DIRTY_READ

This operation will support degree 1 isolation; that is, read operations may return data that has been modified by other transactions but which has not yet been committed. Silently ignored if the DB_DIRTY_READ flag was not specified when the underlying container was opened.

DB_DEGREE_2

This operation will have degree 2 isolation. This provides for cursor stability but not repeatable reads. Data items which have been previously read by this transaction may be deleted or modified by other transactions before this transaction completes.

DBXML_NO_INDEX_NODES

Relevant for node storage containers with node indexes only. Causes the XmlIndexLookup::execute operations to return document nodes rather than direct pointers to the interior nodes. This is more efficient if all that is desired is a reference to target documents.

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.

DBXML_REVERSE_ORDER

Return results in reverse order relative to the sort of the index.

Errors

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

UNKNOWN_INDEX

Unknown index specification

Description: XmlResults XmlContainer::lookupIndex(XmlTransaction &txn, XmlQueryContext &context, const std::string &uri, const std::string &name, const std::string &parent_uri, const std::string &parent_name, const std::string &index, const XmlValue &value = XmlValue(), u_int32_t flags = 0)

Return all the targets for which the identified index has keys. By default, entire documents are returned by this method. However, if node storage containers are in use (the default container type) and if DBXML_INDEX_NODES is set for the container, then this method will return the individual nodes referenced by the index keys.

Use this form of this method to return documents indexed by edge indices.

Edge indices are indices maintained for those locations in a document where two nodes (a parent node and a child node) meet. See the Berkeley DB XML Getting Started Guide for details.

Parameters

txn

If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

context

The XmlQueryContext to use for this query.

uri

The namespace of the node to which this edge index is applied.

name

The name of the node to which this edge index is applied.

parent_uri

The namespace of the parent node to which this edge index is applied.

parent_name

The name of the parent node to which this edge index is applied.

index

Identifies the index for which you want the documents returned. The value supplied here must be a valid index. See XmlIndexSpecification::addIndex for a description of valid index specifications.

value

Provides the value to which equality indices must be equal. This parameter is required when returning documents indexed by equality indices, and it is ignored for all other types of indices.

flags

The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

DB_DIRTY_READ

This operation will support degree 1 isolation; that is, read operations may return data that has been modified by other transactions but which has not yet been committed. Silently ignored if the DB_DIRTY_READ flag was not specified when the underlying container 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.

DBXML_LAZY_DOCS

Retrieve the document lazily. That is, retrieve document content and document metadata only on an as needed basis when reading the document.

Errors

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

UNKNOWN_INDEX

Unknown index specification