| 1 |
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
|
| 2 |
|
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
| 3 |
|
<HTML>
|
| 4 |
|
<HEAD>
|
| 5 |
|
<TITLE>XML-DBMS, Version 1.0</TITLE>
|
| 6 |
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
| 7 |
|
</HEAD>
|
| 8 |
|
<BODY>
|
| 9 |
|
|
| 10 |
|
<CENTER><H1>XML-DBMS, Version 1.0</H1>
|
| 11 |
|
<H2>Java Packages for Transferring Data between<BR />XML Documents and Relational Databases</H2>
|
| 12 |
|
|
| 13 |
|
<P><A HREF="http://www.informatik.tu-darmstadt.de/DVS1/staff/bourret/bourret.htm">Ronald Bourret</A><BR />
|
| 14 |
|
Technical University of Darmstadt</P></CENTER>
|
| 15 |
|
|
| 16 |
|
<H2>Contents</H2>
|
| 17 |
|
|
| 18 |
|
<P>
|
| 19 |
|
<A HREF="#Overview"/>1.0 Overview</A><BR />
|
| 20 |
|
<A HREF="#ObjectView"/>2.0 An Object View of an XML Document</A><BR />
|
| 21 |
|
<A HREF="#Maps"/>3.0 Map Objects, Map Factories, and the XML-DBMS Mapping Language</A><BR />
|
| 22 |
|
<A HREF="#Factories"/>3.1 Map Factories</A><BR />
|
| 23 |
|
<a href="#MapFactory_MapDocument"/>3.1.1 MapFactory_MapDocument</A><BR />
|
| 24 |
|
<a href="#MapFactory_DTD"/>3.1.2 MapFactory_DTD</A><BR />
|
| 25 |
|
<A HREF="#Lang"/>3.2 The XML-DBMS Mapping Language</A><BR />
|
| 26 |
|
<A HREF="#LangSample"/>3.2.1 Sample Documents and Tables</A><BR />
|
| 27 |
|
<A HREF="#LangClass"/>3.2.2 Mapping Classes (Element Types) to Tables</A><BR />
|
| 28 |
|
<A HREF="#LangProp"/>3.2.3 Mapping Properties (Attributes and Element Types) to Columns</A><BR />
|
| 29 |
|
<A HREF="#LangRel"/>3.2.4 Mapping Inter-Class Relationships (Element Hierarchy)</A><BR />
|
| 30 |
|
<A HREF="#LangElim"/>3.2.5 Eliminating Unwanted Root Elements</A><BR />
|
| 31 |
|
<A HREF="#LangMixed"/>3.2.6 Mapping Mixed Content</A><BR />
|
| 32 |
|
<A HREF="#LangNS"/>3.2.7 Using Namespaces</A><BR />
|
| 33 |
|
<A HREF="#Nulls"/>3.2.8 Handling Null Values</A><BR />
|
| 34 |
|
<A HREF="#DateTime"/>3.2.9 Date, Time, and Timestamp Formats</A><BR />
|
| 35 |
|
<A HREF="#ToDBMS">4.0 Transferring Data to the Database</A><BR />
|
| 36 |
|
<A HREF="#ToXML">5.0 Transferring Data to an XML Document</A><BR />
|
| 37 |
|
<A HREF="#Supported">6.0 Supported Parsers and DOM Implementations</A><BR />
|
| 38 |
|
<A HREF="#Namespaces">6.1 Namespace Support</A><BR />
|
| 39 |
|
<A HREF="#DocumentFactories">6.2 Document Factories</A><BR />
|
| 40 |
|
<A HREF="#NotForUse">7.0 Classes Not for General Use</A><BR />
|
| 41 |
|
<A HREF="#Install">8.0 Downloading and Installing XML-DBMS</A><BR />
|
| 42 |
|
<A HREF="#Install">9.0 Samples</A><BR />
|
| 43 |
|
<a href="#TransferSample"/>9.1 Transfer</a><br />
|
| 44 |
|
<a href="#GenerateMapSample"/>9.2 GenerateMap</a><br />
|
| 45 |
|
<a href="#ConvertSchemaSample"/>9.3 ConvertSchema</a><br />
|
| 46 |
|
<A HREF="#Tips"/>10.0 Tips and Tricks</A><br />
|
| 47 |
|
<A HREF="#License">11.0 Licensing and Support</A><BR />
|
| 48 |
|
</P>
|
| 49 |
|
|
| 50 |
|
<H2><A NAME="Overview"/>1.0 Overview</H2>
|
| 51 |
|
|
| 52 |
|
<P>XML-DBMS is a set of Java packages for transferring data between XML documents and relational databases. Programmers use these packages to build systems that transfer data; a sample application can be run from the command line to transfer data between a database and an XML file.</P>
|
| 53 |
|
|
| 54 |
|
<P>XML-DBMS preserves the hierarchical structure of an XML document, as well as the data (character data and attribute values) in that document. If requested, it also preserves the order in which the children at a given level in the hierarchy appear. (For many data-centric applications, such order is not important and the code runs faster without it.)</P>
|
| 55 |
|
|
| 56 |
|
<P>Because XML-DBMS seeks to transfer data, not documents, it does not preserve document type declarations, nor does it preserve physical structure such as entity use, CDATA sections, or document encodings. In particular, it does not attempt to implement a document management system on top of a relational database.</P>
|
| 57 |
|
|
| 58 |
|
<p>For a general discussion of XML and databases, see <a href="http://www.informatik.tu-darmstadt.de/DVS1/staff/bourret/xml/XMLAndDatabases.htm">XML and Databases</a>.</p>
|
| 59 |
|
|
| 60 |
|
<H2><A NAME="ObjectView"/>2.0 An Object View of an XML Document</H2>
|
| 61 |
|
|
| 62 |
|
<P>XML-DBMS views an XML document as a tree of objects and then uses an object-relational mapping to map these objects to a relational database. The tree of objects is not, as one might initially guess, the Document Object Model (DOM). The reason for this is that the DOM models the document itself and not the data in the document.</P>
|
| 63 |
|
|
| 64 |
|
<P>Instead, the tree is constructed by viewing element types as classes, and attributes and PCDATA as properties of those classes. Subordinate element types are viewed as subordinate classes in the tree; that is, an interclass relationship exists between the parent and child classes.</P>
|
| 65 |
|
|
| 66 |
|
<P>The view of element types as classes is not absolute: element types can also be viewed as properties of their parent element type-as-class. This is most useful when an element type contains only PCDATA. However, it is useful in other cases as well. For example, consider an element type that contains a description written in XHTML. Although this description has subelements such as <B> and <P>, these subelements cannot be meaningfully interpreted on their own and it makes more sense to view the contents of the element type as a single value (property) rather than a class.</P>
|
| 67 |
|
|
| 68 |
|
<p>For example, in the following XML document, the SalesOrder and Customer element types might be viewed as classes and the OrderDate and Description element types as properties:</p>
|
| 69 |
|
|
| 70 |
|
<PRE>
|
| 71 |
|
<Orders>
|
| 72 |
|
<SalesOrder SONumber="12345">
|
| 73 |
|
<Customer CustNumber="543">
|
| 74 |
|
<CustName>ABC Industries</CustName>
|
| 75 |
|
<Street>123 Main St.</Street>
|
| 76 |
|
<City>Chicago</City>
|
| 77 |
|
<State>IL</State>
|
| 78 |
|
<PostCode>60609</PostCode>
|
| 79 |
|
</Customer>
|
| 80 |
|
<OrderDate>981215</OrderDate>
|
| 81 |
|
<Line LineNumber="1">
|
| 82 |
|
<Part PartNumber="123">
|
| 83 |
|
<Description>
|
| 84 |
|
<P><B>Turkey wrench:</B><BR />
|
| 85 |
|
Stainless steel, one-piece construction,
|
| 86 |
|
lifetime guarantee.</P>
|
| 87 |
|
</Description>
|
| 88 |
|
<Price>9.95</Price>
|
| 89 |
|
</Part>
|
| 90 |
|
<Quantity>10</Quantity>
|
| 91 |
|
</Line>
|
| 92 |
|
<Line LineNumber="2">
|
| 93 |
|
<Part PartNumber="456">
|
| 94 |
|
<Description>
|
| 95 |
|
<P><B>Stuffing separator:<B><BR />
|
| 96 |
|
Aluminum, one-year guarantee.</P>
|
| 97 |
|
</Description>
|
| 98 |
|
<Price>13.27</Price>
|
| 99 |
|
</Part>
|
| 100 |
|
<Quantity>5</Quantity>
|
| 101 |
|
</Line>
|
| 102 |
|
</SalesOrder>
|
| 103 |
|
</Orders>
|
| 104 |
|
</PRE>
|
| 105 |
|
|
| 106 |
|
<P>Exactly how element types, attributes, and PCDATA are viewed is left to the user, who specifies this information, as well now to map the object view to the database, in a Map object.</P>
|
| 107 |
|
|
| 108 |
|
<H2><A NAME="Maps"/>3.0 Map Objects, Map Factories, and the XML-DBMS Mapping Language</H2>
|
| 109 |
|
|
| 110 |
|
<P>A Map object declares the object view of the element types, attributes, and PCDATA in an XML document and how this view is mapped to the database. Map objects are opaque. That is, the programmer constructs a Map object with a map factory and passes it to the data transfer classes without calling any of its methods. For example, the following code calls a user-defined function to create a Map from a map document and passes it to the class that transfers data from an XML document to the database:</P>
|
| 111 |
|
|
| 112 |
|
<PRE>
|
| 113 |
|
// Use a user-defined function that calls a map
|
| 114 |
|
// factory to create a map. (See section 3.1.)
|
| 115 |
|
map = createMap("sales.map", conn1);
|
| 116 |
|
|
| 117 |
|
// Set the Map on the DOMToDBMS object.
|
| 118 |
|
domToDBMS.setMap(map);
|
| 119 |
|
</PRE>
|
| 120 |
|
|
| 121 |
|
<P>The Map can also be set on the constructor.</P>
|
| 122 |
|
|
| 123 |
|
<P>Note that a Map object can be used multiple times. For example, suppose that a program expects to store four different types of XML documents in the database. It can create the Maps for these documents at start-up, then, as it receives documents to process, pass the appropriate Map to the DOMToDBMS object.</P>
|
| 124 |
|
|
| 125 |
|
<P><b>Disclaimer:</b>I haven't learned how Java multi-threading works, so the following may not be an issue.</p>
|
| 126 |
|
|
| 127 |
|
<p>Assuming it is possible for multiple threads to share the same object, multiple threads should not share the same Map. The reason for this is that a Map contains a reference to a Connection object and the data transfer classes (DBMSToDOM and DOMToDBMS) commit transactions on this object. Since Connection.commit() commits all statements open on a given Connection, a commit executed in one data transfer object will commit statements being used by all other data transfer objects sharing the same Map/Connection. This is unlikely to be the desired behavior.</P>
|
| 128 |
|
|
| 129 |
|
<H3><A NAME="Factories"/>3.1 Map Factories</H3>
|
| 130 |
|
|
| 131 |
|
<P>Currently, XML-DBMS has a two map factories: one to create Map objects from map documents and one to create Map objects from DTDs and schema documents.
|
| 132 |
|
|
| 133 |
|
<h4><a name="MapFactory_MapDocument"/>3.1.1 MapFactory_MapDocument</h4>
|
| 134 |
|
|
| 135 |
|
<p>The MapFactory_MapDocument class creates Map objects from map documents. It is the most commonly used map factory. For example, the following code creates a Map object from the sales.map map document:</P>
|
| 136 |
|
|
| 137 |
|
<PRE>
|
| 138 |
|
// Instantiate a new map factory from a database connection
|
| 139 |
|
// and a SAX parser.
|
| 140 |
|
factory = new MapFactory_MapDocument(conn, parser);
|
| 141 |
|
|
| 142 |
|
// Create a Map from sales.map.
|
| 143 |
|
map = factory.createMap(new InputSource(new FileReader("sales.map")));
|
| 144 |
|
</PRE>
|
| 145 |
|
|
| 146 |
|
<h4><a name="MapFactory_DTD"/>3.1.2 MapFactory_DTD</h4>
|
| 147 |
|
|
| 148 |
|
<p>The MapFactory_DTD class creates Map objects from DTDs and XML schema documents. This factory is designed primarily for use as a tool to help build mapping documents. For example, the following code creates a Map object from document.dtd and then serialized that Map object to a file.</p>
|
| 149 |
|
|
| 150 |
|
<pre>
|
| 151 |
|
// Instantiate a new map factory and create a map.
|
| 152 |
|
factory = new MapFactory_DTD();
|
| 153 |
|
src = new InputSource("file://c:/java/de/tudarmstadt/ito/xmldbms/samples/document.dtd");
|
| 154 |
|
map = factory.createMapFromDTD(src, MapFactory_DTD.DTD_EXTERNAL, true, null);<br />
|
| 155 |
|
|
| 156 |
|
// Open a FileOutputStream and serialize the Map to that stream.
|
| 157 |
|
mapFile = new FileOutputStream("c:\java\de\tudarmstadt\ito\xmldbms\samples\document.map");
|
| 158 |
|
map.serialize(mapFile);
|
| 159 |
|
mapFile.close();
|
| 160 |
|
</pre>
|
| 161 |
|
|
| 162 |
|
<p>Maps created by MapFactory_DTD cannot be used to transfer data until the Map.setConnection method has been called to specify a JDBC Connection.</p>
|
| 163 |
|
|
| 164 |
|
<p>MapFactory_DTD supports DTDs in two forms: either an external subset -- that is, a stand-alone DTD file -- or an XML document containing an internal subset, reference to an external subset, or both. Currently, the only schema language it supports is <a href="http://www.w3.org/TR/NOTE-ddml">DDML (Data Definition Markup Language)</a>. If you need to use another schema language, such as <a href="http://www.w3.org/TR/NOTE-dcd">DCD (Document Content Description for XML)</a>, <a href="http://www.w3.org/TR/NOTE-SOX/">SOX (Schema for Object-Oriented XML)</a>, the <a href="http://www.w3.org/TR/xmlschema-1/">W3C's XML Schema language</a>, or <a href="http://www.ltg.ed.ac.uk/~ht/XMLData-Reduced.htm">XML-Data Reduced</a>, you will need to write a conversion module similar to de.tudarmstadt.ito.schemas.converters.DDMLToDTD.</p>
|
| 165 |
|
|
| 166 |
|
<H3><A NAME="Lang"/>3.2 The XML-DBMS Mapping Language</H3>
|
| 167 |
|
|
| 168 |
|
<P>The XML-DBMS mapping language is a simple, XML-based language that describes both how to construct an object view for an XML document and how to map this view to a relational schema. We will introduce the main parts of the language in a series of examples. For complete information, see the <A HREF="xmldbms.dtd">XML-DBMS DTD</A>.</P>
|
| 169 |
|
|
| 170 |
|
<H4><A NAME="LangSample"/>3.2.1 Sample Documents and Tables</H4>
|
| 171 |
|
|
| 172 |
|
<P>The examples use the sales language shown in <a href="#ObjectView">section 2.0</a>, the document language shown in figure 1, and the tables shown in figures 2 and 3.</p>
|
| 173 |
|
|
| 174 |
|
<hr />
|
| 175 |
|
|
| 176 |
|
<P><B> Figure 1: Sample document in Document language:</B></P>
|
| 177 |
|
|
| 178 |
|
<PRE>
|
| 179 |
|
<!DOCTYPE Product SYSTEM "document.dtd">
|
| 180 |
|
|
| 181 |
|
<Product>
|
| 182 |
|
|
| 183 |
|
<Name>XML-DBMS</Name>
|
| 184 |
|
|
| 185 |
|
<Developer>Ronald Bourret, Technical University of Darmstadt</Developer>
|
| 186 |
|
|
| 187 |
|
<Summary>Java packages for transferring data between
|
| 188 |
|
XML documents and relational databases</Summary>
|
| 189 |
|
|
| 190 |
|
<Description>
|
| 191 |
|
|
| 192 |
|
<Para>XML-DBMS is a set of Java packages for transferring data between
|
| 193 |
|
XML documents and relational databases. It views the XML document as a tree
|
| 194 |
|
of objects in which element types are generally viewed as classes and
|
| 195 |
|
attributes and PCDATA as properties of those classes. It then uses an object-
|
| 196 |
|
relational mapping to map these objects to the database. An XML-based mapping
|
| 197 |
|
language is used to define the view and map it to the database.</Para>
|
| 198 |
|
|
| 199 |
|
<Para>You can:</Para>
|
| 200 |
|
|
| 201 |
|
<List>
|
| 202 |
|
<Item><Link URL="readme.html">Read more about XML-DBMS</Link></Item>
|
| 203 |
|
<Item><Link URL="XMLAndDatabases.htm">Read more about databases and XML</Link></Item>
|
| 204 |
|
<Item><Link URL="xmldbms.dtd">View the mapping language DTD</Link></Item>
|
| 205 |
|
<Item><Link URL="xmldbms.zip">Download XML-DBMS</Link></Item>
|
| 206 |
|
</List>
|
| 207 |
|
|
| 208 |
|
<Para>XML-DBMS, along with its source code, is freely available for use
|
| 209 |
|
in both commercial and non-commercial settings.</Para>
|
| 210 |
|
|
| 211 |
|
</Description>
|
| 212 |
|
|
| 213 |
|
</PRE>
|
| 214 |
|
|
| 215 |
|
<hr />
|
| 216 |
|
|
| 217 |
|
<P><B> Figure 2: Sales data tables:</B></P>
|
| 218 |
|
|
| 219 |
|
<TABLE>
|
| 220 |
|
<TR>
|
| 221 |
|
<TH> </TH>
|
| 222 |
|
<TH ALIGN=LEFT>Sales</TH>
|
| 223 |
|
<TH> </TH>
|
| 224 |
|
<TH ALIGN=LEFT>Lines</TH>
|
| 225 |
|
<TH> </TH>
|
| 226 |
|
<TH ALIGN=LEFT>Customers</TH>
|
| 227 |
|
<TH> </TH>
|
| 228 |
|
<TH ALIGN=LEFT>Parts</TH>
|
| 229 |
|
</TR>
|
| 230 |
|
<TR>
|
| 231 |
|
<TD> </TD>
|
| 232 |
|
<TD>Number</TD>
|
| 233 |
|
<TD> </TD>
|
| 234 |
|
<TD>SONumber</TD>
|
| 235 |
|
<TD> </TD>
|
| 236 |
|
<TD>Number</TD>
|
| 237 |
|
<TD> </TD>
|
| 238 |
|
<TD>Number</TD>
|
| 239 |
|
</TR>
|
| 240 |
|
<TR>
|
| 241 |
|
<TD> </TD>
|
| 242 |
|
<TD>CustNumber</TD>
|
| 243 |
|
<TD> </TD>
|
| 244 |
|
<TD>Number</TD>
|
| 245 |
|
<TD> </TD>
|
| 246 |
|
<TD>Name</TD>
|
| 247 |
|
<TD> </TD>
|
| 248 |
|
<TD>Description</TD>
|
| 249 |
|
</TR>
|
| 250 |
|
<TR>
|
| 251 |
|
<TD> </TD>
|
| 252 |
|
<TD>Date</TD>
|
| 253 |
|
<TD> </TD>
|
| 254 |
|
<TD>Part</TD>
|
| 255 |
|
<TD> </TD>
|
| 256 |
|
<TD>Street</TD>
|
| 257 |
|
<TD> </TD>
|
| 258 |
|
<TD>Price</TD>
|
| 259 |
|
</TR>
|
| 260 |
|
<TR>
|
| 261 |
|
<TD> </TD>
|
| 262 |
|
<TD> </TD>
|
| 263 |
|
<TD> </TD>
|
| 264 |
|
<TD>Quantity</TD>
|
| 265 |
|
<TD> </TD>
|
| 266 |
|
<TD>City</TD>
|
| 267 |
|
<TD> </TD>
|
| 268 |
|
<TD> </TD>
|
| 269 |
|
</TR>
|
| 270 |
|
<TR>
|
| 271 |
|
<TD> </TD>
|
| 272 |
|
<TD> </TD>
|
| 273 |
|
<TD> </TD>
|
| 274 |
|
<TD> </TD>
|
| 275 |
|
<TD> </TD>
|
| 276 |
|
<TD>State</TD>
|
| 277 |
|
<TD> </TD>
|
| 278 |
|
<TD> </TD>
|
| 279 |
|
</TR>
|
| 280 |
|
<TR>
|
| 281 |
|
<TD> </TD>
|
| 282 |
|
<TD> </TD>
|
| 283 |
|
<TD> </TD>
|
| 284 |
|
<TD> </TD>
|
| 285 |
|
<TD> </TD>
|
| 286 |
|
<TD>Country</TD>
|
| 287 |
|
<TD> </TD>
|
| 288 |
|
<TD> </TD>
|
| 289 |
|
</TR>
|
| 290 |
|
<TR>
|
| 291 |
|
<TD> </TD>
|
| 292 |
|
<TD> </TD>
|
| 293 |
|
<TD> </TD>
|
| 294 |
|
<TD> </TD>
|
| 295 |
|
<TD> </TD>
|
| 296 |
|
<TD>PostalCode</TD>
|
| 297 |
|
<TD> </TD>
|
| 298 |
|
<TD> </TD>
|
| 299 |
|
</TR>
|
| 300 |
|
</TABLE>
|
| 301 |
|
|
| 302 |
|
<hr />
|
| 303 |
|
|
| 304 |
|
<P><B> Figure 3: Document data tables:</B></P>
|
| 305 |
|
|
| 306 |
|
<TABLE>
|
| 307 |
|
<TR>
|
| 308 |
|
<TH> </TH>
|
| 309 |
|
<TH ALIGN=LEFT>Product</TH>
|
| 310 |
|
<TH> </TH>
|
| 311 |
|
<TH ALIGN=LEFT>Description</TH>
|
| 312 |
|
<TH> </TH>
|
| 313 |
|
<TH ALIGN=LEFT>Para</TH>
|
| 314 |
|
<TH> </TH>
|
| 315 |
|
<TH ALIGN=LEFT>ParaPCDATA</TH>
|
| 316 |
|
</TR>
|
| 317 |
|
<TR>
|
| 318 |
|
<TD> </TD>
|
| 319 |
|
<TD>ProductID</TD>
|
| 320 |
|
<TD> </TD>
|
| 321 |
|
<TD>ProductID</TD>
|
| 322 |
|
<TD> </TD>
|
| 323 |
|
<TD>DescriptionID</TD>
|
| 324 |
|
<TD> </TD>
|
| 325 |
|
<TD>ParaID</TD>
|
| 326 |
|
</TR>
|
| 327 |
|
<TR>
|
| 328 |
|
<TD> </TD>
|
| 329 |
|
<TD>ProductOrder</TD>
|
| 330 |
|
<TD> </TD>
|
| 331 |
|
<TD>DescriptionID</TD>
|
| 332 |
|
<TD> </TD>
|
| 333 |
|
<TD>ParaID</TD>
|
| 334 |
|
<TD> </TD>
|
| 335 |
|
<TD>ParaPCDATA</TD>
|
| 336 |
|
</TR>
|
| 337 |
|
<TR>
|
| 338 |
|
<TD> </TD>
|
| 339 |
|
<TD>Name</TD>
|
| 340 |
|
<TD> </TD>
|
| 341 |
|
<TD>DescriptionOrder</TD>
|
| 342 |
|
<TD> </TD>
|
| 343 |
|
<TD>ParaOrder</TD>
|
| 344 |
|
<TD> </TD>
|
| 345 |
|
<TD>ParaPCDATAOrder</TD>
|
| 346 |
|
</TR>
|
| 347 |
|
<TR>
|
| 348 |
|
<TD> </TD>
|
| 349 |
|
<TD>NameOrder</TD>
|
| 350 |
|
<TD> </TD>
|
| 351 |
|
<TD> </TD>
|
| 352 |
|
<TD> </TD>
|
| 353 |
|
<TD> </TD>
|
| 354 |
|
<TD> </TD>
|
| 355 |
|
<TD> </TD>
|
| 356 |
|
</TR>
|
| 357 |
|
<TR>
|
| 358 |
|
<TD> </TD>
|
| 359 |
|
<TD>Developer</TD>
|
| 360 |
|
<TD> </TD>
|
| 361 |
|
<TD> </TD>
|
| 362 |
|
<TD> </TD>
|
| 363 |
|
<TD> </TD>
|
| 364 |
|
<TD> </TD>
|
| 365 |
|
<TD> </TD>
|
| 366 |
|
</TR>
|
| 367 |
|
<TR>
|
| 368 |
|
<TD> </TD>
|
| 369 |
|
<TD>DeveloperOrder</TD>
|
| 370 |
|
<TD> </TD>
|
| 371 |
|
<TD> </TD>
|
| 372 |
|
<TD> </TD>
|
| 373 |
|
<TD> </TD>
|
| 374 |
|
<TD> </TD>
|
| 375 |
|
<TD> </TD>
|
| 376 |
|
</TR>
|
| 377 |
|
<TR>
|
| 378 |
|
<TD> </TD>
|
| 379 |
|
<TD>Summary</TD>
|
| 380 |
|
<TD> </TD>
|
| 381 |
|
<TD> </TD>
|
| 382 |
|
<TD> </TD>
|
| 383 |
|
<TD> </TD>
|
| 384 |
|
<TD> </TD>
|
| 385 |
|
<TD> </TD>
|
| 386 |
|
</TR>
|
| 387 |
|
<TR>
|
| 388 |
|
<TD> </TD>
|
| 389 |
|
<TD>SummaryOrder</TD>
|
| 390 |
|
<TD> </TD>
|
| 391 |
|
<TD> </TD>
|
| 392 |
|
<TD> </TD>
|
| 393 |
|
<TD> </TD>
|
| 394 |
|
<TD> </TD>
|
| 395 |
|
<TD> </TD>
|
| 396 |
|
</TR>
|
| 397 |
|
<TR>
|
| 398 |
|
<TD> </TD>
|
| 399 |
|
<TD> </TD>
|
| 400 |
|
<TD> </TD>
|
| 401 |
|
<TD> </TD>
|
| 402 |
|
<TD> </TD>
|
| 403 |
|
<TD> </TD>
|
| 404 |
|
<TD> </TD>
|
| 405 |
|
<TD> </TD>
|
| 406 |
|
</TR>
|
| 407 |
|
<TR>
|
| 408 |
|
<TH> </TH>
|
| 409 |
|
<TH ALIGN=LEFT>List</TH>
|
| 410 |
|
<TH> </TH>
|
| 411 |
|
<TH ALIGN=LEFT>Item</TH>
|
| 412 |
|
<TH> </TH>
|
| 413 |
|
<TH ALIGN=LEFT>ItemPCDATA</TH>
|
| 414 |
|
<TH> </TH>
|
| 415 |
|
<TH ALIGN=LEFT>Link</TH>
|
| 416 |
|
</TR>
|
| 417 |
|
<TR>
|
| 418 |
|
<TD> </TD>
|
| 419 |
|
<TD>DescriptionID</TD>
|
| 420 |
|
<TD> </TD>
|
| 421 |
|
<TD>ListID</TD>
|
| 422 |
|
<TD> </TD>
|
| 423 |
|
<TD>ItemID</TD>
|
| 424 |
|
<TD> </TD>
|
| 425 |
|
<TD>ParaID</TD>
|
| 426 |
|
</TR>
|
| 427 |
|
<TR>
|
| 428 |
|
<TD> </TD>
|
| 429 |
|
<TD>ListID</TD>
|
| 430 |
|
<TD> </TD>
|
| 431 |
|
<TD>ItemID</TD>
|
| 432 |
|
<TD> </TD>
|
| 433 |
|
<TD>ItemPCDATA</TD>
|
| 434 |
|
<TD> </TD>
|
| 435 |
|
<TD>ItemID</TD>
|
| 436 |
|
</TR>
|
| 437 |
|
<TR>
|
| 438 |
|
<TD> </TD>
|
| 439 |
|
<TD>ListOrder</TD>
|
| 440 |
|
<TD> </TD>
|
| 441 |
|
<TD>ItemOrder</TD>
|
| 442 |
|
<TD> </TD>
|
| 443 |
|
<TD>ItemPCDATAOrder</TD>
|
| 444 |
|
<TD> </TD>
|
| 445 |
|
<TD>LinkOrder</TD>
|
| 446 |
|
</TR>
|
| 447 |
|
<TR>
|
| 448 |
|
<TD> </TD>
|
| 449 |
|
<TD> </TD>
|
| 450 |
|
<TD> </TD>
|
| 451 |
|
<TD> </TD>
|
| 452 |
|
<TD> </TD>
|
| 453 |
|
<TD> </TD>
|
| 454 |
|
<TD> </TD>
|
| 455 |
|
<TD>URL</TD>
|
| 456 |
|
</TR>
|
| 457 |
|
<TR>
|
| 458 |
|
<TD> </TD>
|
| 459 |
|
<TD> </TD>
|
| 460 |
|
<TD> </TD>
|
| 461 |
|
<TD> </TD>
|
| 462 |
|
<TD> </TD>
|
| 463 |
|
<TD> </TD>
|
| 464 |
|
<TD> </TD>
|
| 465 |
|
<TD>LinkPCDATA</TD>
|
| 466 |
|
</TR>
|
| 467 |
|
</TABLE>
|
| 468 |
|
|
| 469 |
|
<hr />
|
| 470 |
|
|
| 471 |
|
<H4><A NAME="LangClass"/>3.2.2 Mapping Classes (Element Types) to Tables</H4>
|
| 472 |
|
|
| 473 |
|
<P>Element types with element content are usually viewed as classes and mapped to a table. For example, the following declares the SalesOrder element type to be a class and maps it to the Sales table:</P>
|
| 474 |
|
|
| 475 |
|
<PRE>
|
| 476 |
|
<ClassMap>
|
| 477 |
|
<ElementType Name="SalesOrder"/>
|
| 478 |
|
<ToClassTable>
|
| 479 |
|
<Table Name="Sales"/>
|
| 480 |
|
</ToClassTable>
|
| 481 |
|
...property maps...
|
| 482 |
|
...related class maps...
|
| 483 |
|
...pass-through maps...
|
| 484 |
|
</ClassMap>
|
| 485 |
|
</PRE>
|
| 486 |
|
|
| 487 |
|
<P>The ClassMap element contains all of the information needed to map a single class (element type), including the table to which the class is mapped, the maps for each property in the class, a list of related classes, and a list of passed-through child classes.</P>
|
| 488 |
|
|
| 489 |
|
<P>The ElementType element identifies the element type (class) being mapped and the ToClassTable element gives the name of the table to which the class is mapped.</P>
|
| 490 |
|
|
| 491 |
|
<H4><A NAME="LangProp"/>3.2.3 Mapping Properties (Attributes and Element Types) to Columns</H4>
|
| 492 |
|
|
| 493 |
|
<P>Single-valued attributes and element types with PCDATA-only content are usually viewed as properties and mapped to columns. For example, the following declares the SONumber attribute and the OrderDate element type (when SalesOrder is its parent) to be properties and maps them to the Number and Date columns, respectively. These maps are nested inside the class map for SalesOrder.</P>
|
| 494 |
|
|
| 495 |
|
<PRE>
|
| 496 |
|
<PropertyMap>
|
| 497 |
|
<Attribute Name="SONumber"/>
|
| 498 |
|
<ToColumn>
|
| 499 |
|
<Column Name="Number"/>
|
| 500 |
|
</ToColumn>
|
| 501 |
|
</PropertyMap>
|
| 502 |
|
|
| 503 |
|
<PropertyMap>
|
| 504 |
|
<ElementType Name="OrderDate"/>
|
| 505 |
|
<ToColumn>
|
| 506 |
|
<Column Name="Date"/>
|
| 507 |
|
</ToColumn>
|
| 508 |
|
</PropertyMap>
|
| 509 |
|
</PRE>
|
| 510 |
|
|
| 511 |
|
<P>The Attribute and ElementType elements identify the properties being mapped and the ToColumn elements state that they are being mapped to columns. These columns are understood to be in the table to which the class (SalesOrder) is mapped.</P>
|
| 512 |
|
|
| 513 |
|
<H4><A NAME="LangRel"/>3.2.4 Mapping Inter-Class Relationships (Element Hierarchy)</H4>
|
| 514 |
|
|
| 515 |
|
<P>When a child element type is viewed as a class, its relationship with its parent element type must be stated in the map of the parent class. For example, the following declares that Line is related to the SalesOrder class. This map is nested inside the class map for SalesOrder; the actual mapping of the Line class is separate.</P>
|
| 516 |
|
|
| 517 |
|
<PRE>
|
| 518 |
|
<RelatedClass KeyInParentTable="Candidate">
|
| 519 |
|
<ElementType Name="Line"/>
|
| 520 |
|
<CandidateKey Generate="No">
|
| 521 |
|
<Column Name="Number"/>
|
| 522 |
|
<CandidateKey/>
|
| 523 |
|
<ForeignKey>
|
| 524 |
|
<Column Name="SONumber"/>
|
| 525 |
|
</ForeignKey>
|
| 526 |
|
<OrderColumn Name="Number" Generate="No"/>
|
| 527 |
|
</RelatedClass>
|
| 528 |
|
</PRE>
|
| 529 |
|
|
| 530 |
|
<P>The ElementType element gives the name of the related class and the KeyInParentTable attribute states that the candidate key used to join the tables is in the parent (Sales) table. CandidateKey and ForeignKey give the columns in these keys, which must match in number and type. The Generate attribute of CandidateKey tells the system whether to generate the key. This allows us to preserve keys that have business meaning and generate object identifiers when no such keys exist. In this case, we do not generate the key because we have mapped the SONumber attribute of the SalesOrder element type to the candidate key column (Sales.Number).</P>
|
| 531 |
|
|
| 532 |
|
<P>The (optional) OrderColumn element gives the name of the column that contains information about the order in which Line elements appear in the SalesOrder element. Because this column must appear in the table on the "many" side of the relationship, Number refers to the Lines.Number column, not the Sales.Number column. The Generate attribute of the OrderColumn element tells the system whether to generate the order value. In this case, we do not generate the order value because we will separately map the LineNumber attribute of the Line element type to the order column (Lines.Number).</P>
|
| 533 |
|
|
| 534 |
|
<H4><A NAME="LangElim"/>3.2.5 Eliminating Unwanted Root Elements</H4>
|
| 535 |
|
|
| 536 |
|
<P>Root elements sometimes exist only because XML requires a single root element. For example, in our sales order language, we would like to store multiple sales orders in a single document. To do this, we need the Orders element to encapsulate multiple SalesOrder elements. However, there is no structure in the database corresponding to the Orders element and we would like to eliminate it. For example, the following states that the Orders element type is to be ignored.</P>
|
| 537 |
|
|
| 538 |
|
<PRE>
|
| 539 |
|
<IgnoreRoot>
|
| 540 |
|
<ElementType Name="Orders"/>
|
| 541 |
|
<PseudoRoot>
|
| 542 |
|
<ElementType Name="SalesOrder"/>
|
| 543 |
|
<CandidateKey Generate="No">
|
| 544 |
|
<Column Name="Number"/>
|
| 545 |
|
</CandidateKey>
|
| 546 |
|
</PseudoRoot>
|
| 547 |
|
</IgnoreRoot>
|
| 548 |
|
</PRE>
|
| 549 |
|
|
| 550 |
|
<P>The first ElementType element gives the element type to be ignored. The PseudoRoot element introduces an element type (SalesOrder) to serve as a root in its place; there can be multiple pseudo-roots. The (optional) CandidateKey element gives the key to be used when retrieving data from the database; not shown is an option OrderColumn element that gives the order in which the SalesOrder elements are to be retrieved.</P>
|
| 551 |
|
|
| 552 |
|
<p>Ignored root elements are reconstructed when retrieving data from the database.</p>
|
| 553 |
|
|
| 554 |
|
<H4><A NAME="LangMixed"/>3.2.6 Mapping Mixed Content</H4>
|
| 555 |
|
|
| 556 |
|
<P>Mixed content consists of both PCDATA and elements, such as in our document language. The order in which the PCDATA and elements appear is usually important, so we usually need to keep order information for the PCDATA as well as each element. For example, the following maps the Name element type to the Name column in the Product table and stores system-generated order information in the NameOrder column; this map is nested inside the class map for the Product element type.</P>
|
| 557 |
|
|
| 558 |
|
<PRE>
|
| 559 |
|
<PropertyMap>
|
| 560 |
|
<ElementType Name="Name"/>
|
| 561 |
|
<ToColumn>
|
| 562 |
|
<Column Name="Name"/>
|
| 563 |
|
</ToColumn>
|
| 564 |
|
<OrderColumn Name="NameOrder" Generate="Yes"/>
|
| 565 |
|
</PropertyMap>
|
| 566 |
|
</PRE>
|
| 567 |
|
|
| 568 |
|
<P>Because PCDATA can occur multiple times in mixed content, it is usually mapped to a separate table. For example, the following maps the PCDATA from the Para element type to the ParaPCDATA table; this map is nested inside the class map for the Para element type.</P>
|
| 569 |
|
|
| 570 |
|
<PRE>
|
| 571 |
|
<PropertyMap>
|
| 572 |
|
<PCDATA/>
|
| 573 |
|
<ToPropertyTable KeyInParentTable="Candidate">
|
| 574 |
|
<Table Name="ParaPCDATA"/>
|
| 575 |
|
<CandidateKey Generate="Yes">
|
| 576 |
|
<Column Name="ParaID"/>
|
| 577 |
|
</CandidateKey>
|
| 578 |
|
<ForeignKey>
|
| 579 |
|
<Column Name="ParaID"/>
|
| 580 |
|
</ForeignKey>
|
| 581 |
|
<Column Name="ParaPCDATA"/>
|
| 582 |
|
<OrderColumn Name="ParaPCDATAOrder" Generate="Yes"/>
|
| 583 |
|
</ToPropertyTable>
|
| 584 |
|
</PropertyMap>
|
| 585 |
|
</PRE>
|
| 586 |
|
|
| 587 |
|
<P>The ToPropertyTable element states that the table contains only property values, not a class. In addition to giving the candidate and foreign keys needed to retrieve PCDATA values from the table, we give the names of the columns (ParaPCDATA and ParaPCDATAOrder) in which the PCDATA and order information are stored. Notice that we ask the system to generate both the candidate key (ParaID) and the order information; this is because the document does not contain this information.</P>
|
| 588 |
|
|
| 589 |
|
<p>As you may have noticed, the document language requires more tables and more columns per property than the sales order language. This is because the document language is an example of a <i>document-centric</i> language, while the sales language is an example of a <i>data-centric</i> language.</p>
|
| 590 |
|
|
| 591 |
|
<p>Document-centric languages are used to create documents for human consumption, such as books, email, and advertisements. They are characterized by less predictable structures, coarser-grained data, and large amounts of mixed content and the order in which sibling elements and PCDATA occurs is usually significant. Because order is usually signficant and element types-as-properties and PCDATA generally can occur multiple times in their parent (thus requiring storage in separate tables), document-centric languages require a more complex structure in the database.</P>
|
| 592 |
|
|
| 593 |
|
<p>Data-centric languages tend to describe discrete pieces of data and are typically used to transfer data between applications and data stores. They are characterized by fairly regular structure, fine-grained data (the smallest independent unit of data is usually at the attribute or PCDATA-only element level), and little or no mixed content. The order in which sibling elements and PCDATA occurs is usually not significant. Because of their regular structure and the unimportance of order, data-centric languages require a less complex structure in the database.</P>
|
| 594 |
|
|
| 595 |
|
</p>Although XML-DBMS and relational databases can be used to store documents written in document-centric languages, they are better suited to storing the regular structure encountered in documents written in data-centric languages.</p>
|
| 596 |
|
|
| 597 |
|
<H4><A NAME="LangNS"/>3.2.7 Using Namespaces</H4>
|
| 598 |
|
|
| 599 |
|
<P>Namespaces are supported through Namespace elements, which declare the prefixes and URIs used in the Name attributes of ElementType and Attribute elements. (Note that these prefixes are separate from those declared with xmlns attributes.) For example, suppose the sales order language has a namespace URI of http://ito.tu-darmstadt.de/xmldbms/sales. The map document might contain the following Namespace element, which states that the sales prefix is used in the map document to identify element types and attributes from this namespace.</P>
|
| 600 |
|
|
| 601 |
|
<PRE>
|
| 602 |
|
<Namespace Prefix="sales" URI="http://ito.tu-darmstadt.de/xmldbms/sales"/>
|
| 603 |
|
</PRE>
|
| 604 |
|
|
| 605 |
|
<P>Thus, when mapping the SalesOrder element type, the following reference is used:</P>
|
| 606 |
|
|
| 607 |
|
<PRE>
|
| 608 |
|
<ElementType Name="sales:SalesOrder"/>
|
| 609 |
|
</PRE>
|
| 610 |
|
|
| 611 |
|
<P>As with namespaces in XML documents, unprefixed attribute names referenced in the Name attribute of the Attribute element type do not belong to any XML namespace. (For those of you who are confused by this statement, remember that such attribute names must be unique within their element type; this is a requirement imposed by the XML specification and has nothing to do with XML namespaces.) For example, in the following class map, the SONumber attribute is assumed to belong to the SalesOrder element type; it does not belong to any XML namespace.</P>
|
| 612 |
|
|
| 613 |
|
<PRE>
|
| 614 |
|
<ClassMap>
|
| 615 |
|
<ElementType Name="sales:SalesOrder"/>
|
| 616 |
|
<ToClassTable>
|
| 617 |
|
<Table Name="Sales"/>
|
| 618 |
|
</ToClassTable>
|
| 619 |
|
<PropertyMap>
|
| 620 |
|
<Attribute Name="SONumber"/>
|
| 621 |
|
<ToColumn>
|
| 622 |
|
<Column Name="Number"/>
|
| 623 |
|
</ToColumn>
|
| 624 |
|
</PropertyMap>
|
| 625 |
|
</ClassMap>
|
| 626 |
|
</PRE>
|
| 627 |
|
|
| 628 |
|
<P>Prefixes used in the map document do not need to match those used in instance documents. All that is important is that the namespace URIs are the same. Currently, Namespace elements do not support empty prefixes; that is, you cannot declare a namespace URI that will be associated with unprefixed element type and attribute names in the map document.</P>
|
| 629 |
|
|
| 630 |
|
<P>Whether a document using namespaces can actually be processed depends on the DOM implementation being used. For more information, see section 6.1, "<A HREF="#Namespaces">Namespace Support</A>".</P>
|
| 631 |
|
|
| 632 |
|
<H4><A NAME="Nulls"/>3.2.8 Handling Null Values</H4>
|
| 633 |
|
|
| 634 |
|
<p>A null value is a value that simply isn't there. This is very different from a value of 0 (for numbers) or zero length (for a string). For example, suppose you have data collected from a weather station. If the thermometer isn't working, a null value is stored in the database rather than a 0, which would mean something different altogether.</p>
|
| 635 |
|
|
| 636 |
|
<p>XML also supports the concept of null data through optional element types and attributes. If the value of an optional element type or attribute is null, it simply isn't included in the document. As with databases, empty elements or attributes containing zero length strings are not null: their value is a zero-length string.</p>
|
| 637 |
|
|
| 638 |
|
<p>In spite of this definition of null values, it is quite likely that XML documents will use empty (zero-length) strings to represent null values. Because of this, the EmptyStringIsNull element can be used to state how empty strings are treated. If it is present, empty strings are treated in the same way as null values. If it is absent, empty strings are treated as strings. For example, the following states that empty strings should be treated as nulls.
|
| 639 |
|
|
| 640 |
|
<pre>
|
| 641 |
|
<EmptyStringIsNull/>
|
| 642 |
|
</pre>
|
| 643 |
|
|
| 644 |
|
<p>The EmptyStringIsNull element is nested inside the Options element. Note that it applies only to element types and attributes mapped as propertys. An empty element-as-class with no attributes results in a row of all NULLs in the database.</p>
|
| 645 |
|
|
| 646 |
|
<H4><A NAME="DateTime"/>3.2.9 Date, Time, and Timestamp Formats</H4>
|
| 647 |
|
|
| 648 |
|
<p>Because XML documents are international, it is likely that you will encounter a variety of date, time, and timestamp formats. You can specify the formats to use with the DateTimeFormats element, which contains an optional Locale element and a Patterns element that specifies the actual formatting patterns to use. For example, the following specifies that dates use the "dd.MM.yy" format (e.g. 29.10.58), times use the "HH:mm" format (e.g. 18:37), and timestamps use the "MMM d, yyyy h:mm a" (e.g. February 9, 1962 6:35 AM).
|
| 649 |
|
|
| 650 |
|
<pre>
|
| 651 |
|
<DateTimeFormats>
|
| 652 |
|
<Patterns Date="HH:mm" Time="HH:mm" Timestamp="MMM d, yyyy h:mm"/>
|
| 653 |
|
</DateTimeFormats>
|
| 654 |
|
</pre>
|
| 655 |
|
|
| 656 |
|
<p>Like EmptyStringIsNull, the DateTimeFormats element is nested inside the Options element. The formats used are defined in the java.text.DateFormat and java.text.SimpleDateFormat classes.</p>
|
| 657 |
|
|
| 658 |
|
<H2><A NAME="ToDBMS"/>4.0 Transferring Data to the Database</H2>
|
| 659 |
|
|
| 660 |
|
<P>The DOMToDBMS class transfers data from a DOM tree to the database according to a given Map. For example, the following code transfers data from the sales_in.xml document to the database according to the Map object created from sales.map:</P>
|
| 661 |
|
|
| 662 |
|
<PRE>
|
| 663 |
|
// Use a user-defined function to create a map.
|
| 664 |
|
map = createMap("sales.map", conn1);
|
| 665 |
|
|
| 666 |
|
// Use a user-defined function to create a DOM tree over sales_in.xml
|
| 667 |
|
doc = openDocument("sales_in.xml");
|
| 668 |
|
|
| 669 |
|
// Create a new DOMToDBMS object and store the data.
|
| 670 |
|
domToDBMS = new DOMToDBMS(map);
|
| 671 |
|
docInfo = domToDBMS.storeDocument(doc);
|
| 672 |
|
</PRE>
|
| 673 |
|
|
| 674 |
|
<P>Information about how to retrieve the data at a later point in time is returned in a DocumentInfo object, which is just a list of table names, key column names, key values, and order column names.</P>
|
| 675 |
|
|
| 676 |
|
<P>If DOMToDBMS needs to generate key values, as in our <A HREF="#LangMixed">document example</A>, the caller must provide an object that implements the KeyGenerator interface. DOMToDBMS calls a method this object to get unique key values; a default implementation of this object (KeyGeneratorImpl), which generates unique 4-byte integers, can be found in the de.tudarmstadt.ito.xmldbms.helpers package. For example:</P>
|
| 677 |
|
|
| 678 |
|
<PRE>
|
| 679 |
|
// Use a user-defined function to create a map.
|
| 680 |
|
Map map = createMap("document.map", conn1);
|
| 681 |
|
|
| 682 |
|
// Use a user-defined function to create a DOM tree over document_in.xml
|
| 683 |
|
doc = openDocument("document_in.xml");
|
| 684 |
|
|
| 685 |
|
// Instantiate KeyGeneratorImpl and initialize it with a Connection.
|
| 686 |
|
keyGenerator = new KeyGeneratorImpl();
|
| 687 |
|
keyGenerator.initialize(conn2);
|
| 688 |
|
|
| 689 |
|
// Create a new DOMToDBMS object and set the KeyGenerator.
|
| 690 |
|
domToDBMS = new DOMToDBMS(map);
|
| 691 |
|
domToDBMS.setKeyGenerator(keyGenerator);
|
| 692 |
|
|
| 693 |
|
// Store the data.
|
| 694 |
|
docInfo = domToDBMS.storeDocument(doc);
|
| 695 |
|
</PRE>
|
| 696 |
|
|
| 697 |
|
<P>The KeyGenerator can also be set on the constructor.</P>
|
| 698 |
|
|
| 699 |
|
<P>Note that the KeyGeneratorImpl object and the DOMToDBMS object use different connections to the same database. This is because each commits transactions at different times and using the same connection for both objects would lead to statements being committed prematurely.</P>
|
| 700 |
|
|
| 701 |
|
<H2><A NAME="ToXML"/>5.0 Transferring Data to an XML Document</H2>
|
| 702 |
|
|
| 703 |
|
<P>The DBMSToDOM class transfers data from the database to a DOM tree according to a given Map. For example, the following code transfers data for sales order number 123 from the Sales table to the sales_out.xml document according to the Map object created from sales.map:</P>
|
| 704 |
|
|
| 705 |
|
<PRE>
|
| 706 |
|
// Use a user-defined function to create a map.
|
| 707 |
|
map = createMap("sales.map", conn);
|
| 708 |
|
|
| 709 |
|
// Create a new DBMSToDOM object.
|
| 710 |
|
dbmsToDOM = new DBMSToDOM(map, new DF_Oracle());
|
| 711 |
|
|
| 712 |
|
// Create a key and retrieve the data.
|
| 713 |
|
key = {new Integer(123)};
|
| 714 |
|
doc = dbmsToDOM.retrieveDocument("Sales", key);
|
| 715 |
|
</PRE>
|
| 716 |
|
|
| 717 |
|
<P>Note that the DBMSToDOM object is created with a DocumentFactory (DF_Oracle) that can create Documents for Oracle's implementation of the DOM. For more information, see section 6.2, "<A HREF="#DocumentFactories">Document Factories</A>".
|
| 718 |
|
|
| 719 |
|
<P>The DBMSToDOM class has four different retrieveDocument methods. In addition to the method shown above, there are methods that accept arrays of tables and keys, a DocumentInfo object, and a ResultSet object as arguments. In the latter case, the Map object must map an element type to the table named "Result Set".</P>
|
| 720 |
|
|
| 721 |
|
<P>If the data specified by the parameters of a retrieveDocument method contains more than one row, the Map object must specify an ignored root type. Otherwise, DBMSToDOM will attempt to add more than one root element to the document, resulting in a DOMException. (Note that this does not include rows of data retrieved from subordinate tables.)</P>
|
| 722 |
|
|
| 723 |
|
<H2><A NAME="Supported"/>6.0 Supported Parsers and DOM Implementations</H2>
|
| 724 |
|
|
| 725 |
|
<P>XML-DBMS is written in a parser and DOM-neutral fashion and should be able to use any parser that supports SAX and any Java implementation of the DOM. Unfortunately, there are no standard ways to support namespaces in the DOM, nor are there standard ways to create empty DOM documents. Thus, these capabilities are encapsulated in the NameQualifier and DocumentFactory interfaces in the de.tudarmstadt.ito.domutils package.</P>
|
| 726 |
|
|
| 727 |
|
<H3><A NAME="Namespaces"/>6.1 Namespace Support</H3>
|
| 728 |
|
|
| 729 |
|
<P>The DOM specification does not define how namespaces are supported. Thus, some DOM implementations have defined methods for retrieving various information about the namespace used by a given Node. We have encapsulated a subset of this information in the NameQualifier interface. This interface uses the following definitions:</P>
|
| 730 |
|
|
| 731 |
|
<DL>
|
| 732 |
|
<DT>Local name</DT>
|
| 733 |
|
<DD>The unprefixed name of a node.<DD>
|
| 734 |
|
<DT>Prefixed name</DT>
|
| 735 |
|
<DD>The prefixed name of a node. If there is no namespace URI, the prefixed name is the same as the local name.<DD>
|
| 736 |
|
<DT>Qualified name</DT>
|
| 737 |
|
<DD>The namespace URI, plus a caret (^), plus the local name. If there is no namespace URI, the qualified name is the same as the local name.</DD>
|
| 738 |
|
</DL>
|
| 739 |
|
|
| 740 |
|
<P>For example:</P>
|
| 741 |
|
|
| 742 |
|
<PRE>
|
| 743 |
|
<foo:element1 xmlns="http://foo">
|
| 744 |
|
Local name: "element1"
|
| 745 |
|
Prefixed name: "foo:element1"
|
| 746 |
|
Qualified name: "http://foo^element1"
|
| 747 |
|
|
| 748 |
|
<element2>
|
| 749 |
|
Local name: "element2"
|
| 750 |
|
Prefixed name: "element2"
|
| 751 |
|
Qualified name: "element2"
|
| 752 |
|
</PRE>
|
| 753 |
|
|
| 754 |
|
<P>To use namespaces, the DOM implementation must support namespaces and the Map object must declare the namespace URI (if any) of each mapped element type and attribute (see section 3.2.7, "<A HREF="#LangNS"/>Using Namespaces</A>"). If a DOM implementation does not support namespaces, then the element type and attribute names in the Map object must exactly match the names returned by the DOM's implementation Node.getNodeName(). Usually, this will be the prefixed name.</P>
|
| 755 |
|
|
| 756 |
|
<P>When transferring data from an XML document to the database, the caller must pass an object that implements the NameQualifier interface to the DOMToDBMS object. For example, the following code passes a NameQualifier for Oracle's DOM implementation:</P>
|
| 757 |
|
|
| 758 |
|
<PRE>
|
| 759 |
|
domToDBMS.setNameQualifier(new NQ_Oracle());
|
| 760 |
|
</PRE>
|
| 761 |
|
|
| 762 |
|
<P>The NameQualifier may also be set in the constructor and no NameQualifier is needed if neither the XML document nor the Map uses namespaces. The de.tudarmstadt.ito.domutils package includes implementations of NameQualifier for DataChannel (Microsoft), IBM, Oracle, and Sun. As of this writing, Docuverse and OpenXML do not support namespaces. However, you should check whether a newer version of either implemenation does; implementing NameQualifier yourself is trivial.</P>
|
| 763 |
|
|
| 764 |
|
<P>When transferring data from the database to an XML document, the caller must choose how namespaces will be used. Currently, no DOM implementations support setting the namespace or prefix of an element or attribute. Thus, the caller can choose whether element and attribute names are prefixed according to the namespace prefixes in the Map or no prefixes are used at all.</P>
|
| 765 |
|
|
| 766 |
|
<P>Prefixing the element and attribute names in the returned DOM tree is useful if the DOM tree is to be serialized as XML. However, it will probably cause problems if the DOM tree is to be used directly. The reason for this is that the DOM implementation will not correctly recognize and return the unprefixed name, the namespace URI, or the qualified name. By default, prefixes are not used. The following code shows how to request that prefixes be used:</P>
|
| 767 |
|
|
| 768 |
|
<PRE>
|
| 769 |
|
dbmsToDOM.usePrefixes(true);
|
| 770 |
|
</PRE>
|
| 771 |
|
|
| 772 |
|
<H3><A NAME="DocumentFactories"/>6.2 Document Factories</H3>
|
| 773 |
|
|
| 774 |
|
<P>Like namespace support, there is no standard way to create an empty DOM Document. Thus, we have encapsulated this functionality in the DocumentFactory interface. When transferring data from the database to an XML document, an object implementing this interface must be passed to the DBMSToDOM object. For example, the following code uses the DocumentFactory for Oracle:</P>
|
| 775 |
|
|
| 776 |
|
<PRE>
|
| 777 |
|
dbmsToDOM.setDocumentFactory(new DF_Oracle());
|
| 778 |
|
</PRE>
|
| 779 |
|
|
| 780 |
|
<P>The DocumentFactory may also be set in the constructor. The de.tudarmstadt.ito.domutils package contains implementations of DocumentFactory for the DataChannel (Microsoft), Docuverse, IBM, OpenXML, Oracle, and Sun DOM implementations. Be sure to check that these implementations match the version of the implementation you are using. If not, you may need to implement DocumentFactory yourself; doing so is trivial.</P>
|
| 781 |
|
|
| 782 |
|
<H2><A NAME="NotForUse"/>7.0 Classes Not for General Use</H2>
|
| 783 |
|
|
| 784 |
|
<P>The de.tudarmstadt.ito.xmldbms package contains a number of public classes that are not for general use. That is, programmers using XML-DBMS do not need to instantiate or call methods on these classes. These classes are used to map XML document structures to database structures and are public so that they can be used by map factories, which are in a different package.</P>
|
| 785 |
|
|
| 786 |
|
<P>The not-for-general-use mapping classes are:</P>
|
| 787 |
|
|
| 788 |
|
<PRE>
|
| 789 |
|
ClassMap
|
| 790 |
|
Column
|
| 791 |
|
ColumnMap
|
| 792 |
|
LinkInfo
|
| 793 |
|
MapOptions
|
| 794 |
|
OrderInfo
|
| 795 |
|
PropertyMap
|
| 796 |
|
RelatedClassMap
|
| 797 |
|
RootClassMap
|
| 798 |
|
RootTableMap
|
| 799 |
|
Table
|
| 800 |
|
TableMap
|
| 801 |
|
</PRE>
|
| 802 |
|
|
| 803 |
|
<P>A special case is the Map class. For programmers using XML-DBMS, this is generally treated as an opaque object. That is, the programmer gets a Map object from a map factory and passes it to DOMToDBMS or DBMSToDOM. In addition, the Map object has public methods that some (but not all) XML-DBMS programmers use, such as methods to serialize the map to an OutputStream and to get CREATE TABLE statements. Although many variables in the Map class are public, programmers should never need to access them.</P>
|
| 804 |
|
|
| 805 |
|
<P>It is possible for programmers to directly create objects in the mapping classes, but it is strongly recommended that a map factory be used instead. Note that DOMToDBMS and DBMSToDOM largely assume that the objects in these classes have been created correctly, so using incorrectly constructed objects has unpredictable results. However, should a programmer be brave (foolish?) enough to construct these objects by hand, a slightly simplified hierarchy of them is as follows:</P>
|
| 806 |
|
|
| 807 |
|
<PRE>
|
| 808 |
|
Map
|
| 809 |
|
Table (array of)
|
| 810 |
|
TableMap (array of)
|
| 811 |
|
RootClassMap (hashtable of)
|
| 812 |
|
ClassMap
|
| 813 |
|
PropertyMap (hashtable of)
|
| 814 |
|
RelatedClassMap (hashtable of)
|
| 815 |
|
ClassMap...
|
| 816 |
|
LinkInfo
|
| 817 |
|
OrderInfo
|
| 818 |
|
LinkInfo
|
| 819 |
|
OrderInfo
|
| 820 |
|
RootTableMap (hashtable of)
|
| 821 |
|
TableMap
|
| 822 |
|
Table
|
| 823 |
|
Column (array of)
|
| 824 |
|
ColumnMap (array of)
|
| 825 |
|
Column
|
| 826 |
|
TableMap... (array of)
|
| 827 |
|
</PRE>
|
| 828 |
|
|
| 829 |
|
<H2><A NAME="Install"/>8.0 Downloading and Installing XML-DBMS</H2>
|
| 830 |
|
<P>You can download the current version of XML-DBMS from <A HREF="http://www.informatik.tu-darmstadt.de/DVS1/staff/bourret/xmldbms/xmldbms.htm">here</A>.</P>
|
| 831 |
|
|
| 832 |
|
<P>To install, unzip the downloaded file and add xmldbms.jar to your CLASSPATH.</P>
|
| 833 |
|
|
| 834 |
|
<P>XML-DBMS has been used with JDK versions 1.1.8 and 1.2 and a number of different databases and JDBC drivers.</P>
|
| 835 |
|
|
| 836 |
|
<H2><A NAME="Samples"/>9.0 Samples</H2>
|
| 837 |
|
|
| 838 |
|
<P>XML-DBMS comes with three samples, Transfer, GenerateMap, and ConvertSchema, which can be found in the samples subdirectory.</p>
|
| 839 |
|
|
| 840 |
|
<h3><a name="TransferSample"/>9.1 Transfer</h3>
|
| 841 |
|
<i>Transfer</i> is a simple command-line application that transfers data between an XML file and the database according to a particular map document. It shows how to use the MapFactory_MapDocument, DOMToDBMS, DBMSToDOM, and Map classes.</P>
|
| 842 |
|
|
| 843 |
|
<P>When transferring data from an XML document to the database, use the command:</P>
|
| 844 |
|
|
| 845 |
|
<PRE>
|
| 846 |
|
java Transfer -todbms <map-file> <xml-file>
|
| 847 |
|
</PRE>
|
| 848 |
|
|
| 849 |
|
<P>For example, to transfer data from the sample file document_in.xml to the database according the map document document.map, use the command:</P>
|
| 850 |
|
|
| 851 |
|
<PRE>
|
| 852 |
|
java Transfer -todbms document.map document_in.xml
|
| 853 |
|
</PRE>
|
| 854 |
|
|
| 855 |
|
<P>When transferring data from the database to an XML document, use the command:</P>
|
| 856 |
|
|
| 857 |
|
<PRE>
|
| 858 |
|
java Transfer -todbms <map-file> <xml-file> <table-name> <key-value>...
|
| 859 |
|
</PRE>
|
| 860 |
|
|
| 861 |
|
<P>where <key-value> is one or more values in a single key. (There are multiple values only if the key is multi-part.) For example, to transfer data for sales order number 123 from the Sales table to the file sales_out.xml according to the map document sales.map, use the command:</P>
|
| 862 |
|
|
| 863 |
|
<PRE>
|
| 864 |
|
java Transfer -toxml sales.map sales_out_in.xml Sales 123
|
| 865 |
|
</PRE>
|
| 866 |
|
|
| 867 |
|
<P>The Transfer application requires an ODBC data source named "xmldbms", an ODBC driver for that database, and that the tables referred to in the map exist in that database. Furthermore, if the map specifies that the system generate key values, the table XMLDBMSKey must exist; for more information, see de.tudarmstadt.ito.xmldbms.helpers.KeyGeneratorImpl.</P>
|
| 868 |
|
|
| 869 |
|
<h3><a name="GenerateMapSample"/>9.2 GenerateMap</h3>
|
| 870 |
|
<i>GenerateMap</i> is a simple command-line application that generates a map and a set of CREATE TABLE statements from a DTD, an XML document containing or referring to a DTD, or a DDML schema document. The map is saved in a document with the .map extension and the CREATE TABLE statements are saved in a document with the .sql extension. It shows how to use the MapFactory_DTD and Map classes.</P>
|
| 871 |
|
|
| 872 |
|
<P>To run GenerateMap, use the command:</P>
|
| 873 |
|
|
| 874 |
|
<PRE>
|
| 875 |
|
java GenerateMap <DTD or XML document>
|
| 876 |
|
</PRE>
|
| 877 |
|
|
| 878 |
|
<P>For example, to generate a map from the document DTD, use the command:</P>
|
| 879 |
|
|
| 880 |
|
<PRE>
|
| 881 |
|
java GenerateMap document.dtd
|
| 882 |
|
</PRE>
|
| 883 |
|
|
| 884 |
|
<P>The GenerateMap application requires an ODBC data source named "xmldbms" and an ODBC driver for that database. It does not require that the database contain any tables -- it simply needs to retrieve information from the database about how to construct the CREATE TABLE statements. </P>
|
| 885 |
|
|
| 886 |
|
<h3><a name="ConvertSchemaSample"/>9.3 ConvertSchema</h3>
|
| 887 |
|
<i>ConvertSchema</i> is a simple command-line application that converts schema documents to DTDs and vice versa. Currently, only DDML-to-DTD and DTD-to-DDML are supported, but writing converters to other schema languages is relatively easy -- a half day to day per direction. Although this sample has nothing to do with databases, it does show the capabilities of some of the schema conversion classes (SubsetToDTD, DDMLToDTD, DTDToDDML, and DTD), which might be useful in other applications.</P>
|
| 888 |
|
|
| 889 |
|
<P>To convert a schema document to a DTD or vice versa, use the command:</P>
|
| 890 |
|
|
| 891 |
|
<PRE>
|
| 892 |
|
java ConvertSchema <schema-file>
|
| 893 |
|
</PRE>
|
| 894 |
|
|
| 895 |
|
<P>For example, to convert the document.ddm DDML document to a DTD, use the command:</P>
|
| 896 |
|
|
| 897 |
|
<PRE>
|
| 898 |
|
java ConvertSchema document.ddm
|
| 899 |
|
</PRE>
|
| 900 |
|
|
| 901 |
|
<P>To convert a DTD to convert the document.dtd DTD to a DDML document, use the command:</P>
|
| 902 |
|
|
| 903 |
|
<PRE>
|
| 904 |
|
java ConvertSchema document.dtd
|
| 905 |
|
</PRE>
|
| 906 |
|
|
| 907 |
|
<H2><A NAME="Tips"/>10.0 Tips and Tricks</H2>
|
| 908 |
|
|
| 909 |
|
<p>Here is a short list of ways that might help your code run faster:</p>
|
| 910 |
|
|
| 911 |
|
<ul>
|
| 912 |
|
|
| 913 |
|
<li>Reuse Map objects if you need to transfer data from multiple documents to the database or vice versa. For details, see section 3.0, "<a href="#Maps">Map Objects, Map Factories, and the XML-DBMS Mapping Language</a>".</li>
|
| 914 |
|
|
| 915 |
|
<li>Use a pool of SELECT statements when transferring data from the database to an XML file. For details, see the comments in the code for Map.checkInSelectStatement.</li>
|
| 916 |
|
|
| 917 |
|
<li>Close your prepared statements before discarding a Map object. For details, see Map.closeStatements().</li>
|
| 918 |
|
|
| 919 |
|
</ul>
|
| 920 |
|
|
| 921 |
|
<H2><A NAME="License"/>11.0 Licensing and Support</H2>
|
| 922 |
|
|
| 923 |
|
<P>XML-DBMS, along with its source code, is freely available for use in both commercial and non-commercial settings. It is not copyrighted and has <B>absolutely no warranty</B>. Use it as you will.</P>
|
| 924 |
|
|
| 925 |
|
<P>Although I am no longer at the Technical University of Darmstadt, you can still get limited support by emailing me at <A HREF="mailto:rpbourret@aol.com">rpbourret@aol.com</A> or <A HREF="mailto:rpbourret@hotmail.com">rpbourret@hotmail.com</A>. Because I will be travelling and not in regular contact with email, expect a one- to two-week delay. Bug reports and comments are welcome. There is also a list of <A HREF="BugsEnhancements.htm">known bugs and suggested enhancements</a>.</P>
|
| 926 |
|
|
| 927 |
|
<p>Thanks to all those who have given me feedback and sent in bug reports. Special thanks to Richard Sullivan, Matthias Pfisterer, and Alf Hogemark for their helpful comments, suggestions for new features, code, and testing.</p>
|
| 928 |
|
|
| 929 |
|
</BODY>
|
| 930 |
|
</HTML>
|
| 931 |
|
|
| 932 |
0 |
|
removed old xmldbms source tree because it is no longer being used as a reference