# XmlContainer::declareIndex

`

###

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

- none-none-none-none
- node-element-presence
- node-attribute-presence
- node-element-equality-string
- node-element-equality-number
- node-element-substring-string
- node-attribute-equality-string
- node-attribute-equality-number
- node-attribute-substring-string
- edge-element-presence
- edge-attribute-presence
- edge-element-equality-string
- edge-element-equality-number
- edge-element-substring-string
- edge-attribute-equality-string
- edge-attribute-equality-number
- edge-attribute-substring-string

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.

`

Copyright Sleepycat Software