Every XML document stored in BDB XML actually consists of two kinds of information: the document itself, and metadata.

Metadata can contain an arbitrarily complex set of information. Typically it contains information about the document that you do not or can not include in the document itself. As an example, you could carry information about the date and time a document was added to the container, last modified, or possibly an expiration time. Metadata might also be used to store information about the document that is external to BDB XML, such as the on-disk location where the document was originally stored, or possibly notes about the document that might be useful to the document's maintainer.

In other words, metadata can contain anything — BDB XML places no restrictions on what you can use it for. Further, you can both query and index metadata (see Using BDB XML Indices for more information). It is even possible to have a document in your container that contains only metadata.

In order to set metadata onto a document, you must:

For example:

#include "DbXml.hpp"
...
                                                                                                                                     
using namespace DbXml;
int main(void)
{
    // The document
    std::string fileName = "/export/testdoc1.xml";

    // The document's name.
    std::string docName = "testDoc1";

    // URI, attribute name, and attribute value used for
    // the metadata. We will carry a timestamp here
    // (hard coded for clarity purposes).
    std::string URI = "http://dbxmlExamples/metadata";
    std::string attrName = "createdOn";
    XmlValue attrValue(XmlValue::DATE_TIME, "2005-10-5T04:18:36");
                                                                                                                                     
    // Get a manager object.
    XmlManager myManager;   // The manager is closed when
                            // it goes out of scope.

    // Load the document in its entirety. The document's formatting is 
    // preserved.
    myManager.setDefaultContainerType(XmlContainer::WholedocContainer);

    // Open the container. The container is closed when it goes
    // out of scope.
    XmlContainer myContainer = 
        myManager.openContainer("container.bdbxml");

    // Need an update context for the put.
    XmlUpdateContext theContext = myManager.createUpdateContext();

    try {
        // Get the input stream.
        XmlInputStream *theStream = 
            myManager.createLocalFileInputStream(fileName);

        // Get an XmlDocument
        XmlDocument myDoc = myManager.createDocument();

        // Set the document's name
        myDoc.setName(docName);
        // Set the content
        myDoc.setContentAsXmlInputStream(theStream);
        // Set the metadata
        myDoc.setMetaData(URI, attrName, attrValue);

        // Put the document into the container
        myContainer.putDocument(myDoc,        // The actual document.
                                 theContext,  // The update context 
                                              // (required).
                                 0);          // Put flags.
    } catch (XmlException &e) {
        // Error handling goes here. You may want to check
        // for XmlException::UNIQUE_ERROR, which is raised
        // if a document with that name already exists in
        // the container. If this exception is thrown, 
        // try the put again with a different name.
    }

    return(0);
}