+ +

Introduction

+ +

This guide shows how to integrate the + C++/Tree + mapping generated by + CodeSynthesis XSD + with + Berkeley DB XML. + + Berkeley DB XML is an embedded XML database which allows efficient + storage and query of XML instance documents. + + CodeSynthesis XSD is a W3C XML Schema to C++ data binding compiler. + + The C++/Tree mapping allows you to manipulate the data stored in XML + using objects that semantically correspond to your application + domain rather than dealing with direct representations of XML. + + For an introduction to + the Berkeley DB XML refer to the + Berkeley DB XML + Getting Started Guide. + For an introduction to the C++/Tree mapping refer to + the C++/Tree Mapping Getting Started Guide. +

+ + +

This guide describes the following four operations:

+ +

Create a new document in DB from an object model
Create an object model from a document in DB
Create an object model from a document fragment in DB
Update a document fragment in DB from an object model

+ +

Our examples will be based on simple XML for book library. The XML + Schema definition for the library is in + library.xsd and is compiled by XSD + to obtain library.hxx and library.cxx. + All C++ code fragments that are presented in this guide are available + as a single program in driver.cxx. + The complete example is available in the + examples/cxx/tree/dbxml directory of the XSD distribution.

+ +

Note that due to the incomplete DOM API implementation provided by DB + XML (as of version 2.3.10), the generated code and your application + should be compiled with the DBXML_DOM macro defined in + order to avoid using unsupported parts of the API. +

+ +

A sample XML document for the library schema is presented below:

+ +

+<lib:catalog xmlns:lib="http://www.codesynthesis.com/library">
+  <book available="true" id="ES">
+    <isbn>20530902</isbn>
+    <title>The Elements of Style</title>
+    <genre>reference</genre>
+
+    <author>
+      <name>William Strunk, Jr.</name>
+      <born>1869-07-01</born>
+      <died>1946-09-26</died>
+    </author>
+
+    <author>
+      <name>E.B. White</name>
+      <born>1899-07-11</born>
+      <died>1985-10-01</died>
+    </author>
+  </book>
+</lib:catalog>
+

+ +

Create Document from Object Model

+ +

In this step, we will programmatically create a book catalog + with one book, save it into an XmlDocument object + using one of the serialization functions generated by XSD ( + catalog_ in our case), and store the + XmlDocument object as a new document in the + DB container:

+ +

+XmlManager manager;
+XmlContainer container (manager.createContainer ("new.bdbxml"));
+XmlUpdateContext update_context (manager.createUpdateContext ());
+XmlQueryContext context (manager.createQueryContext ());
+context.setNamespace ("lib", "http://www.codesynthesis.com/library");
+
+// Create a new catalog with one book.
+//
+catalog c;
+
+book b (20530902,                        // ISBN
+        title ("The Elements of Style"), // Title
+        genre::reference,                // Genre
+        "ES");                           // ID
+
+author strunk ("William Strunk, Jr.", date (1869, 7, 1));
+strunk.died (date (1946, 9, 26));
+
+b.author ().push_back (strunk);
+c.book ().push_back (b);
+
+// Create a new XML document.
+//
+XmlDocument doc (manager.createDocument ());
+doc.setName ("new.xml");
+
+// Obtain its DOM representation and add the root element.
+//
+xercesc::DOMDocument& dom_doc (*doc.getContentAsDOM ());
+
+dom_doc.appendChild (
+  dom_doc.createElementNS (
+    xml::string ("http://www.codesynthesis.com/library").c_str (),
+    xml::string ("lib:catalog").c_str ()));
+
+// Serialize the object model to the XML document. Also avoid
+// re-initializing the Xerces-C++ runtime since XmlManager has
+// it initialized.
+//
+catalog_ (dom_doc, c, xml_schema::flags::dont_initialize);
+
+// Place the document into the container.
+//
+container.putDocument (doc, update_context);
+

+ +

If we now resolve the new.xml in the container and + print its content, we will get:

+ +

+<lib:catalog xmlns:lib="http://www.codesynthesis.com/library">
+  <book available="true" id="ES">
+    <isbn>20530902</isbn>
+    <title>The Elements of Style</title>
+    <genre>reference</genre>
+    <author>
+      <name>William Strunk, Jr.</name>
+      <born>1869-07-01</born>
+      <died>1946-09-26</died>
+    </author>
+  </book>
+</lib:catalog>
+

+ +

Create Object Model from Document

+ +

Creating an object model from a document is a matter + of obtaining XmlDocument object and passing its DOM + representation to one of the parsing functions generated by XSD + (catalog_ in our case): +

+ +

+// Resolve the document in the container.
+//
+XmlDocument doc (container.getDocument ("new.xml"));
+
+// Create the object model from the document's DOM. Also avoid
+// re-initializing the Xerces-C++ runtime since XmlManager has
+// it initialized.
+//
+auto_ptr<catalog> c (catalog_ (*doc.getContentAsDOM (),
+                               xml_schema::flags::dont_initialize));
+
+cerr << *c << endl;
+

+ +

This code fragment prints:

+ +

+book:
+isbn: 20530902
+title: The Elements of Style
+genre: reference
+author:
+name: William Strunk, Jr.
+born: 1869-07-01
+died: 1946-09-26
+available: 1
+id: ES
+

+ +

Create Object Model from Document Fragment

+ +

The following code fragment looks up the book with id "ES" + using XQuery. It then creates a book object from the + resulting XmlValue:

+ +

+string query ("collection('new.bdbxml')/lib:catalog/book[@id='ES']");
+
+// Find "The Elements of Style".
+//
+XmlValue v;
+XmlResults results (manager.query (query, context));
+
+if (results.next (v))
+{
+  // Create an object model from the document fragment.
+  //
+  auto_ptr<book> b (
+    new book (
+      *static_cast<xercesc::DOMElement*> (v.asNode ())));
+
+  cerr << *b << endl;
+}
+

+ +

This code fragment prints:

+ +

+isbn: 20530902
+title: The Elements of Style
+genre: reference
+author:
+name: William Strunk, Jr.
+born: 1869-07-01
+died: 1946-09-26
+available: 1
+id: ES
+

+ +

Note that we had to perform a static_cast from + xercesc::DOMNode + returned by the XmlValue::asNode member function to + xercesc::DOMElement. This is safe since we know + that in our schema books are represented as XML elements.

+ +

Update Document Fragment from Object Model

+ +

Analogous to the create case, the following code fragment looks + up the book with id "ES" using XQuery. It then creates + a book object from the resulting XmlValue, + adds another author, changes the availability status, and saves + the changes back to the XmlValue object: +

+ +

+string query ("collection('new.bdbxml')/lib:catalog/book[@id='ES']");
+
+// Find "The Elements of Style".
+//
+XmlValue v;
+XmlResults results (manager.query (query, context));
+
+if (results.next (v))
+{
+  // Create an object model from the document fragment.
+  //
+  auto_ptr<book> b (
+    new book (
+      *static_cast<xercesc::DOMElement*> (v.asNode ())));
+
+  // Add another author, change the availability status.
+  //
+  author white ("E.B. White", date (1899, 7, 11));
+  white.died (date (1985, 10, 1));
+
+  b->author ().push_back (white);
+  b->available (false);
+
+  // Update the document fragment from the object model.
+  //
+  *static_cast<xercesc::DOMElement*> (v.asNode ()) << *b;
+
+  // Update the document in the container.
+  //
+  XmlDocument doc (v.asDocument ());
+  container.updateDocument (doc, update_context);
+}
+

+ +

If we now resolve the new.xml in the container and + print its content, we will get:

+ +

+<lib:catalog xmlns:lib="http://www.codesynthesis.com/library">
+  <book available="false" id="ES">
+    <isbn>20530902</isbn>
+    <title>The Elements of Style</title>
+    <genre>reference</genre>
+    <author>
+      <name>William Strunk, Jr.</name>
+      <born>1869-07-01</born>
+      <died>1946-09-26</died>
+    </author>
+    <author>
+      <name>E.B. White</name>
+      <born>1899-07-11</born>
+      <died>1985-10-01</died>
+    </author>
+  </book>
+</lib:catalog>
+

+ +