XmlContainer.declareIndex

APIRef

import com.sleepycat.dbxml.*;

public void declareIndex(DbTxn txnid, String node, String index, int flags) throws XmlException;

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