summaryrefslogtreecommitdiff
path: root/xsd/documentation/cxx/tree/dbxml/index.xhtml
diff options
context:
space:
mode:
Diffstat (limited to 'xsd/documentation/cxx/tree/dbxml/index.xhtml')
-rw-r--r--xsd/documentation/cxx/tree/dbxml/index.xhtml348
1 files changed, 348 insertions, 0 deletions
diff --git a/xsd/documentation/cxx/tree/dbxml/index.xhtml b/xsd/documentation/cxx/tree/dbxml/index.xhtml
new file mode 100644
index 0000000..adfeb24
--- /dev/null
+++ b/xsd/documentation/cxx/tree/dbxml/index.xhtml
@@ -0,0 +1,348 @@
+<?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="&copy; 2006-2010 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 <code>library.hxx</code> and <code>library.cxx</code>.
+ 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>
+
+ <p>A sample XML document for the library schema is presented below:</p>
+
+ <pre>
+&lt;lib:catalog xmlns:lib="http://www.codesynthesis.com/library">
+ &lt;book available="true" id="ES">
+ &lt;isbn>20530902&lt;/isbn>
+ &lt;title>The Elements of Style&lt;/title>
+ &lt;genre>reference&lt;/genre>
+
+ &lt;author>
+ &lt;name>William Strunk, Jr.&lt;/name>
+ &lt;born>1869-07-01&lt;/born>
+ &lt;died>1946-09-26&lt;/died>
+ &lt;/author>
+
+ &lt;author>
+ &lt;name>E.B. White&lt;/name>
+ &lt;born>1899-07-11&lt;/born>
+ &lt;died>1985-10-01&lt;/died>
+ &lt;/author>
+ &lt;/book>
+&lt;/lib:catalog>
+ </pre>
+
+ <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&amp; 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>
+&lt;lib:catalog xmlns:lib="http://www.codesynthesis.com/library">
+ &lt;book available="true" id="ES">
+ &lt;isbn>20530902&lt;/isbn>
+ &lt;title>The Elements of Style&lt;/title>
+ &lt;genre>reference&lt;/genre>
+ &lt;author>
+ &lt;name>William Strunk, Jr.&lt;/name>
+ &lt;born>1869-07-01&lt;/born>
+ &lt;died>1946-09-26&lt;/died>
+ &lt;/author>
+ &lt;/book>
+&lt;/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&lt;catalog> c (catalog_ (*doc.getContentAsDOM (),
+ xml_schema::flags::dont_initialize));
+
+cerr &lt;&lt; *c &lt;&lt; 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&lt;book> b (
+ new book (
+ *static_cast&lt;xercesc::DOMElement*> (v.asNode ())));
+
+ cerr &lt;&lt; *b &lt;&lt; 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&lt;book> b (
+ new book (
+ *static_cast&lt;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&lt;xercesc::DOMElement*> (v.asNode ()) &lt;&lt; *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>
+&lt;lib:catalog xmlns:lib="http://www.codesynthesis.com/library">
+ &lt;book available="false" id="ES">
+ &lt;isbn>20530902&lt;/isbn>
+ &lt;title>The Elements of Style&lt;/title>
+ &lt;genre>reference&lt;/genre>
+ &lt;author>
+ &lt;name>William Strunk, Jr.&lt;/name>
+ &lt;born>1869-07-01&lt;/born>
+ &lt;died>1946-09-26&lt;/died>
+ &lt;/author>
+ &lt;author>
+ &lt;name>E.B. White&lt;/name>
+ &lt;born>1899-07-11&lt;/born>
+ &lt;died>1985-10-01&lt;/died>
+ &lt;/author>
+ &lt;/book>
+&lt;/lib:catalog>
+ </pre>
+
+ </div>
+ <div id="footer">
+ &copy;2006-2010 <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>