#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)

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.

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.

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

• The XmlQueryContext to use for this query.

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

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

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

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

• 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_READ_UNCOMMITTED
  • 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_READ_UNCOMMITTED flag was not specified when the underlying container was opened.
  DB_READ_COMMITTED
  • 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 indices 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 read, if locking is configured. 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.
  
  

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

• Unknown index specification

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.

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

• The XmlQueryContext to use for this query.

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

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

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

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

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

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

• The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
  DB_READ_UNCOMMITTED
  • 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_READ_UNCOMMITTED flag was not specified when the underlying container was opened.
  DB_RMW
  • Acquire write locks instead of read locks when doing the read, if locking is configured. 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.
  
  

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

• Unknown index specification