diff options
Diffstat (limited to 'documentation/cxx/tree/dbxml/index.xhtml')
| -rw-r--r-- | documentation/cxx/tree/dbxml/index.xhtml | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/documentation/cxx/tree/dbxml/index.xhtml b/documentation/cxx/tree/dbxml/index.xhtml new file mode 100644 index 0000000..e4e01e6 --- /dev/null +++ b/documentation/cxx/tree/dbxml/index.xhtml @@ -0,0 +1,350 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> + +<head> + <title>C++/Tree Mapping and Berkeley DB XML Integration Guide</title> + + <meta name="copyright" content="© 2006-2009 Code Synthesis Tools CC"/> + <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,berkeley,db,dbxml"/> + <meta name="description" content="C++/Tree Mapping and Berkeley DB XML Integration Guide"/> + + <link rel="stylesheet" type="text/css" href="../../../default.css" /> + +<style type="text/css"> + pre { + background : #cde8f6; + + padding : 0 0 0 1em; + margin : 2em 0em 2em 0; + + } + + h1 {padding-top: 1em;} + +</style> +</head> + +<body> +<div id="container"> + <div id="content"> + + <h1>Introduction</h1> + + <p>This guide shows how to integrate the + <a href="http://www.codesynthesis.com/products/xsd/c++/tree/">C++/Tree</a> + mapping generated by + <a href="http://www.codesynthesis.com/products/xsd/">CodeSynthesis XSD</a> + with + <a href="http://www.oracle.com/database/berkeley-db/xml/index.html">Berkeley DB XML</a>. + + 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 + <a href="http://www.oracle.com/database/berkeley-db/xml/index.html">Berkeley DB XML + Getting Started Guide</a>. + For an introduction to the C++/Tree mapping refer to + the <a href="../guide/">C++/Tree Mapping Getting Started Guide</a>. + </p> + + + <p>This guide describes the following four operations:</p> + + <ul> + <li>Create a new document in DB from an object model</li> + <li>Create an object model from a document in DB</li> + <li>Create an object model from a document fragment in DB</li> + <li>Update a document fragment in DB from an object model</li> + </ul> + + <p>Our examples will be based on simple XML for book library. The XML + Schema definition for the library is in + <a href="./library.xsd">library.xsd</a> and is compiled by XSD + to obtain <a href="./library.hxx">library.hxx</a> and + <a href="./library.cxx">library.cxx</a>. A sample XML document + is presented below:</p> + + <pre> +<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> + </pre> + + <p>All C++ code fragments that are presented in this guide are available + as a single program in <a href="./driver.cxx">driver.cxx</a>. + The complete example is available in the + <code>examples/cxx/tree/dbxml</code> directory of the XSD distribution. + </p> + + <p>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 <code>DBXML_DOM</code> macro defined in + order to avoid using unsupported parts of the API. + </p> + + <h1>Create Document from Object Model</h1> + + <p>In this step, we will programmatically create a book catalog + with one book, save it into an <code>XmlDocument</code> object + using one of the serialization functions generated by XSD ( + <code>catalog_</code> in our case), and store the + <code>XmlDocument</code> object as a new document in the + DB container:</p> + + <pre> +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); + </pre> + + <p>If we now resolve the <code>new.xml</code> in the container and + print its content, we will get:</p> + + <pre> +<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> + </pre> + + <h1>Create Object Model from Document</h1> + + <p>Creating an object model from a document is a matter + of obtaining <code>XmlDocument</code> object and passing its DOM + representation to one of the parsing functions generated by XSD + (<code>catalog_</code> in our case): + </p> + + <pre> +// 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; + </pre> + + <p>This code fragment prints:</p> + + <pre> +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 + </pre> + + <h1>Create Object Model from Document Fragment</h1> + + <p>The following code fragment looks up the book with id <code>"ES"</code> + using XQuery. It then creates a <code>book</code> object from the + resulting <code>XmlValue</code>:</p> + + <pre> +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; +} + </pre> + +<p>This code fragment prints:</p> + + <pre> +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 + </pre> + + <p>Note that we had to perform a <code>static_cast</code> from + <code>xercesc::DOMNode</code> + returned by the <code>XmlValue::asNode</code> member function to + <code>xercesc::DOMElement</code>. This is safe since we know + that in our schema books are represented as XML elements.</p> + + <h1>Update Document Fragment from Object Model</h1> + + <p>Analogous to the create case, the following code fragment looks + up the book with id <code>"ES"</code> using XQuery. It then creates + a <code>book</code> object from the resulting <code>XmlValue</code>, + adds another author, changes the availability status, and saves + the changes back to the <code>XmlValue</code> object: + </p> + + <pre> +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); +} + </pre> + + <p>If we now resolve the <code>new.xml</code> in the container and + print its content, we will get:</p> + + <pre> +<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> + </pre> + + </div> + <div id="footer"> + ©2006-2009 <a href="http://www.codesynthesis.com">CODE SYNTHESIS TOOLS CC</a> + + <div id="terms"> + Permission is granted to copy, distribute and/or modify this + document under the terms of the + <a href="http://www.codesynthesis.com/licenses/fdl-1.2.txt">GNU Free + Documentation License, version 1.2</a>; with no Invariant Sections, + no Front-Cover Texts and no Back-Cover Texts. + </div> + </div> + +</div> + +</body> +</html> |