Setting Metadata
Prev  Chapter 4. Adding XML Documents to Containers  Next

Setting Metadata

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:

  1. Optionally (but recommended), create a URI for each piece of metadata (in the form of a string).

  2. Create an attribute name to use for the metadata, again in the form of a string.

  3. Create the attribute value — the actual metadata information that you want to carry on the document — either as an XmlValue or as an Java byte[] array.

  4. Set this information on a XmlDocument object.

  5. Optionally (but commonly) set the actual XML document to the same XmlDocument object.

  6. Add the XmlDocument to the container.

For example: 

package dbxml.gettingStarted;
                                                                                                                                     
import com.sleepycat.dbxml.XmlContainer;
import com.sleepycat.dbxml.XmlDocument;
import com.sleepycat.dbxml.XmlException;
import com.sleepycat.dbxml.XmlInputStream;
import com.sleepycat.dbxml.XmlManager;
import com.sleepycat.dbxml.XmlValue;

...

XmlManager myManager = null;
XmlContainer myContainer = null;

// The document
String docString = "/export/testdoc1.xml";

// The document's name.
String docName = "testDoc1";


try {
    // URI, attribute name, and attribute value used for
    // the metadata. We will carry a timestamp here
    // (hard coded for clarity purposes).
    String URI = "http://dbxmlExamples/metadata";
    String attrName = "createdOn";
    XmlValue attrValue =
         new XmlValue(XmlValue.DATE_TIME, "2005-10-5T04:18:36");

    myManager = new XmlManager();
    // Assumes the container currently exists.

    myContainer = 
        myManager.openContainer("container.bdbxml");

    // 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.
                             null);       // XmlDocumentConfig object
} 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.
} finally {
    try {
        if (myContainer != null) {
            myContainer.close();
        }

        if (myManager != null) {
            myManager.close();
        }
    } catch (XmlException ce) {
        // Exception handling goes here
    }
}
Prev  Up  Next
Constructing Documents using Event Writers  Home  Chapter 5. Using XQuery with BDB XML