XmlContainer::declareIndex

APIRef

#include <DbXml.hpp>

void XmlContainer::declareIndex(DbTxn *txnid, const std::string &node, const std::string &index, u_int32_t flags);

Description

The XmlContainer::declareIndex method declares the indexing required for a particular node. The node may be an element or attribute.

The node parameter provides the name of the node to be indexed. Attribute node names are prefixed with the '@' character to distinguish them from element node names. For example, within the following XML document fragment the element name is 'fruit', and the attribute name is '@color', "<fruit color='red'>apple</fruit>".

A fully qualified node name is a node name that includes its full namespace specification. In the following fragment from the W3C XML Namespaces specification, the fully qualified name of the "price units" element is "http://ecommerce.org/schema:price units":

<x xmlns:edi='http://ecommerce.org/schema'>
    <!-- the 'price' element's namespace is http://ecommerce.org/schema -->
    <edi:price units='Euro'>32.18</edi:price>
</x>

The index string is a comma separated list of one or more of the following indexing strategy names:

Indices may only be declared for empty containers. Once documents have been added to a container the indexing specification for the container may not be changed.

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

The flags parameter is currently unused, and must be set to 0.

The XmlContainer::declareIndex method throws an exception that encapsulates a non-zero error value on failure.

Errors

The XmlContainer::declareIndex method may fail and throw an UNREF==xmlexception_class exception with the following exception code:

CONTAINER_NOT_EMPTY
Indexes may only be declared for empty containers.

CONTAINER_CLOSED
Indexes may only be declared on open containers.

DATABASE_ERROR
An error occurred in an underlying Berkeley DB database. UNREF==xml_getdberror method returns the error code for the error.

The XmlContainer::declareIndex method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the XmlContainer::declareIndex method may fail and throw a DbRunRecoveryException, in which case all subsequent Berkeley DB calls will fail in the same way.

Class

XmlContainer, XmlDocument, XmlQueryContext

See Also

XmlContainer::close, XmlContainer::declareIndex, XmlContainer::deleteDocument, XmlContainer::getDocument, XmlContainer::getName, XmlContainer::open, XmlContainer::putDocument and XmlContainer::queryWithXPath.

XmlDocument::getAttributeValue, XmlDocument::getContent, XmlDocument::getID, XmlDocument::getName, XmlDocument::getType, XmlDocument::setContent, XmlDocument::setName, and XmlDocument::setType.

APIRef

Copyright Sleepycat Software