Project

General

Profile

metacat / xmldbms / readme.html @ 180

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
&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#Factories"/>3.1 Map Factories</A><BR />
23
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MapFactory_MapDocument"/>3.1.1 MapFactory_MapDocument</A><BR />
24
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MapFactory_DTD"/>3.1.2 MapFactory_DTD</A><BR />
25
&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#Lang"/>3.2 The XML-DBMS Mapping Language</A><BR />
26
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangSample"/>3.2.1 Sample Documents and Tables</A><BR />
27
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangClass"/>3.2.2 Mapping Classes (Element Types) to Tables</A><BR />
28
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangProp"/>3.2.3 Mapping Properties (Attributes and Element Types) to Columns</A><BR />
29
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangRel"/>3.2.4 Mapping Inter-Class Relationships (Element Hierarchy)</A><BR />
30
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangElim"/>3.2.5 Eliminating Unwanted Root Elements</A><BR />
31
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangMixed"/>3.2.6 Mapping Mixed Content</A><BR />
32
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#LangNS"/>3.2.7 Using Namespaces</A><BR />
33
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#Nulls"/>3.2.8 Handling Null Values</A><BR />
34
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<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
&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#Namespaces">6.1 Namespace Support</A><BR />
39
&nbsp;&nbsp;&nbsp;&nbsp;<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
&nbsp;&nbsp;&nbsp;<a href="#TransferSample"/>9.1 Transfer</a><br />
44
&nbsp;&nbsp;&nbsp;<a href="#GenerateMapSample"/>9.2 GenerateMap</a><br />
45
&nbsp;&nbsp;&nbsp;<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 &lt;B&gt; and &lt;P&gt;, 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
   &lt;Orders&gt;
72
      &lt;SalesOrder SONumber="12345"&gt;
73
         &lt;Customer CustNumber="543"&gt;
74
            &lt;CustName&gt;ABC Industries&lt;/CustName&gt;
75
            &lt;Street&gt;123 Main St.&lt;/Street&gt;
76
            &lt;City&gt;Chicago&lt;/City&gt;
77
            &lt;State&gt;IL&lt;/State&gt;
78
            &lt;PostCode&gt;60609&lt;/PostCode&gt;
79
         &lt;/Customer&gt;
80
         &lt;OrderDate&gt;981215&lt;/OrderDate&gt;
81
         &lt;Line LineNumber="1"&gt;
82
            &lt;Part PartNumber="123"&gt;
83
               &lt;Description&gt;
84
                  &lt;P&gt;&lt;B&gt;Turkey wrench:&lt;/B&gt;&lt;BR /&gt;
85
                  Stainless steel, one-piece construction,
86
                  lifetime guarantee.&lt;/P&gt;
87
               &lt;/Description&gt;
88
               &lt;Price&gt;9.95&lt;/Price&gt;
89
            &lt;/Part&gt;
90
            &lt;Quantity&gt;10&lt;/Quantity&gt;
91
         &lt;/Line&gt;
92
         &lt;Line LineNumber="2"&gt;
93
            &lt;Part PartNumber="456"&gt;
94
               &lt;Description&gt;
95
                  &lt;P&gt;&lt;B&gt;Stuffing separator:&lt;B&gt;&lt;BR /&gt;
96
                  Aluminum, one-year guarantee.&lt;/P&gt;
97
               &lt;/Description&gt;
98
               &lt;Price&gt;13.27&lt;/Price&gt;
99
            &lt;/Part&gt;
100
            &lt;Quantity&gt;5&lt;/Quantity&gt;
101
         &lt;/Line&gt;
102
      &lt;/SalesOrder&gt;
103
   &lt;/Orders&gt;
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>&nbsp;&nbsp;&nbsp;Figure 1: Sample document in Document language:</B></P>
177

    
178
<PRE>
179
   &lt;!DOCTYPE Product SYSTEM "document.dtd"&gt;
180

    
181
   &lt;Product&gt;
182

    
183
   &lt;Name&gt;XML-DBMS&lt;/Name&gt;
184

    
185
   &lt;Developer&gt;Ronald Bourret, Technical University of Darmstadt&lt;/Developer&gt;
186

    
187
   &lt;Summary&gt;Java packages for transferring data between
188
   XML documents and relational databases&lt;/Summary&gt;
189

    
190
   &lt;Description&gt;
191

    
192
   &lt;Para&gt;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.&lt;/Para&gt;
198
   
199
   &lt;Para&gt;You can:&lt;/Para&gt;
200
   
201
   &lt;List&gt;
202
   &lt;Item&gt;&lt;Link URL="readme.html"&gt;Read more about XML-DBMS&lt;/Link&gt;&lt;/Item&gt;
203
   &lt;Item&gt;&lt;Link URL="XMLAndDatabases.htm"&gt;Read more about databases and XML&lt;/Link&gt;&lt;/Item&gt;
204
   &lt;Item&gt;&lt;Link URL="xmldbms.dtd"&gt;View the mapping language DTD&lt;/Link&gt;&lt;/Item&gt;
205
   &lt;Item&gt;&lt;Link URL="xmldbms.zip"&gt;Download XML-DBMS&lt;/Link&gt;&lt;/Item&gt;
206
   &lt;/List&gt;
207
   
208
   &lt;Para&gt;XML-DBMS, along with its source code, is freely available for use
209
   in both commercial and non-commercial settings.&lt;/Para&gt;
210
   
211
   &lt;/Description&gt;
212
   
213
</PRE>
214

    
215
<hr />
216

    
217
<P><B>&nbsp;&nbsp;&nbsp;Figure 2: Sales data tables:</B></P>
218

    
219
<TABLE>
220
  <TR>
221
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
222
   <TH ALIGN=LEFT>Sales</TH>
223
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
224
   <TH ALIGN=LEFT>Lines</TH>
225
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
226
   <TH ALIGN=LEFT>Customers</TH>
227
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
228
   <TH ALIGN=LEFT>Parts</TH>
229
  </TR>
230
  <TR>
231
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
232
   <TD>Number</TD>
233
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
234
   <TD>SONumber</TD>
235
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
236
   <TD>Number</TD>
237
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
238
   <TD>Number</TD>
239
  </TR>
240
  <TR>
241
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
242
   <TD>CustNumber</TD>
243
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
244
   <TD>Number</TD>
245
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
246
   <TD>Name</TD>
247
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
248
   <TD>Description</TD>
249
  </TR>
250
  <TR>
251
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
252
   <TD>Date</TD>
253
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
254
   <TD>Part</TD>
255
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
256
   <TD>Street</TD>
257
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
258
   <TD>Price</TD>
259
  </TR>
260
  <TR>
261
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
262
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
263
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
264
   <TD>Quantity</TD>
265
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
266
   <TD>City</TD>
267
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
268
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
269
  </TR>
270
  <TR>
271
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
272
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
273
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
274
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
275
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
276
   <TD>State</TD>
277
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
278
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
279
  </TR>
280
  <TR>
281
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
282
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
283
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
284
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
285
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
286
   <TD>Country</TD>
287
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
288
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
289
  </TR>
290
  <TR>
291
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
292
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
293
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
294
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
295
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
296
   <TD>PostalCode</TD>
297
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
298
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
299
  </TR>
300
</TABLE>
301

    
302
<hr />
303

    
304
<P><B>&nbsp;&nbsp;&nbsp;Figure 3: Document data tables:</B></P>
305

    
306
<TABLE>
307
  <TR>
308
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
309
   <TH ALIGN=LEFT>Product</TH>
310
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
311
   <TH ALIGN=LEFT>Description</TH>
312
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
313
   <TH ALIGN=LEFT>Para</TH>
314
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
315
   <TH ALIGN=LEFT>ParaPCDATA</TH>
316
  </TR>
317
  <TR>
318
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
319
   <TD>ProductID</TD>
320
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
321
   <TD>ProductID</TD>
322
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
323
   <TD>DescriptionID</TD>
324
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
325
   <TD>ParaID</TD>
326
  </TR>
327
  <TR>
328
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
329
   <TD>ProductOrder</TD>
330
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
331
   <TD>DescriptionID</TD>
332
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
333
   <TD>ParaID</TD>
334
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
335
   <TD>ParaPCDATA</TD>
336
  </TR>
337
  <TR>
338
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
339
   <TD>Name</TD>
340
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
341
   <TD>DescriptionOrder</TD>
342
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
343
   <TD>ParaOrder</TD>
344
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
345
   <TD>ParaPCDATAOrder</TD>
346
  </TR>
347
  <TR>
348
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
349
   <TD>NameOrder</TD>
350
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
351
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
352
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
353
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
354
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
355
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
356
  </TR>
357
  <TR>
358
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
359
   <TD>Developer</TD>
360
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
361
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
362
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
363
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
364
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
365
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
366
  </TR>
367
  <TR>
368
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
369
   <TD>DeveloperOrder</TD>
370
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
371
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
372
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
373
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
374
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
375
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
376
  </TR>
377
  <TR>
378
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
379
   <TD>Summary</TD>
380
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
381
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
382
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
383
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
384
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
385
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
386
  </TR>
387
  <TR>
388
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
389
   <TD>SummaryOrder</TD>
390
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
391
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
392
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
393
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
394
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
395
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
396
  </TR>
397
  <TR>
398
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
399
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
400
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
401
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
402
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
403
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
404
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
405
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
406
  </TR>
407
  <TR>
408
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
409
   <TH ALIGN=LEFT>List</TH>
410
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
411
   <TH ALIGN=LEFT>Item</TH>
412
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
413
   <TH ALIGN=LEFT>ItemPCDATA</TH>
414
   <TH>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TH>
415
   <TH ALIGN=LEFT>Link</TH>
416
  </TR>
417
  <TR>
418
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
419
   <TD>DescriptionID</TD>
420
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
421
   <TD>ListID</TD>
422
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
423
   <TD>ItemID</TD>
424
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
425
   <TD>ParaID</TD>
426
  </TR>
427
  <TR>
428
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
429
   <TD>ListID</TD>
430
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
431
   <TD>ItemID</TD>
432
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
433
   <TD>ItemPCDATA</TD>
434
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
435
   <TD>ItemID</TD>
436
  </TR>
437
  <TR>
438
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
439
   <TD>ListOrder</TD>
440
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
441
   <TD>ItemOrder</TD>
442
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
443
   <TD>ItemPCDATAOrder</TD>
444
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
445
   <TD>LinkOrder</TD>
446
  </TR>
447
  <TR>
448
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
449
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
450
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
451
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
452
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
453
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
454
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
455
   <TD>URL</TD>
456
  </TR>
457
  <TR>
458
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
459
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
460
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
461
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
462
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
463
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
464
   <TD>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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
   &lt;ClassMap&gt;
477
      &lt;ElementType Name="SalesOrder"/&gt;
478
      &lt;ToClassTable&gt;
479
         &lt;Table Name="Sales"/&gt;
480
      &lt;/ToClassTable&gt;
481
      ...property maps...
482
      ...related class maps...
483
      ...pass-through maps...
484
   &lt;/ClassMap&gt;
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
   &lt;PropertyMap&gt;
497
      &lt;Attribute Name="SONumber"/&gt;
498
      &lt;ToColumn&gt;
499
         &lt;Column Name="Number"/&gt;
500
      &lt;/ToColumn&gt;
501
   &lt;/PropertyMap&gt;
502

    
503
   &lt;PropertyMap&gt;
504
      &lt;ElementType Name="OrderDate"/&gt;
505
      &lt;ToColumn&gt;
506
         &lt;Column Name="Date"/&gt;
507
      &lt;/ToColumn&gt;
508
   &lt;/PropertyMap&gt;
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
   &lt;RelatedClass KeyInParentTable="Candidate"&gt;
519
      &lt;ElementType Name="Line"/&gt;
520
      &lt;CandidateKey Generate="No"&gt;
521
         &lt;Column Name="Number"/&gt;
522
      &lt;CandidateKey/&gt;
523
      &lt;ForeignKey&gt;
524
         &lt;Column Name="SONumber"/&gt;
525
      &lt;/ForeignKey&gt;
526
      &lt;OrderColumn Name="Number" Generate="No"/&gt;
527
   &lt;/RelatedClass&gt;
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
   &lt;IgnoreRoot&gt;
540
      &lt;ElementType Name="Orders"/&gt;
541
      &lt;PseudoRoot&gt;
542
         &lt;ElementType Name="SalesOrder"/&gt;
543
         &lt;CandidateKey Generate="No"&gt;
544
            &lt;Column Name="Number"/&gt;
545
         &lt;/CandidateKey&gt;
546
      &lt;/PseudoRoot&gt;
547
   &lt;/IgnoreRoot&gt;
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
   &lt;PropertyMap&gt;
560
      &lt;ElementType Name="Name"/&gt;
561
      &lt;ToColumn&gt;
562
         &lt;Column Name="Name"/&gt;
563
      &lt;/ToColumn&gt;
564
      &lt;OrderColumn Name="NameOrder" Generate="Yes"/&gt;
565
   &lt;/PropertyMap&gt;
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
   &lt;PropertyMap&gt;
572
      &lt;PCDATA/&gt;
573
      &lt;ToPropertyTable KeyInParentTable="Candidate"&gt;
574
         &lt;Table Name="ParaPCDATA"/&gt;
575
         &lt;CandidateKey Generate="Yes"&gt;
576
            &lt;Column Name="ParaID"/&gt;
577
         &lt;/CandidateKey&gt;
578
         &lt;ForeignKey&gt;
579
            &lt;Column Name="ParaID"/&gt;
580
         &lt;/ForeignKey&gt;
581
         &lt;Column Name="ParaPCDATA"/&gt;
582
         &lt;OrderColumn Name="ParaPCDATAOrder" Generate="Yes"/&gt;
583
      &lt;/ToPropertyTable&gt;
584
   &lt;/PropertyMap&gt;
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
   &lt;Namespace Prefix="sales" URI="http://ito.tu-darmstadt.de/xmldbms/sales"/&gt;
603
</PRE>
604

    
605
<P>Thus, when mapping the SalesOrder element type, the following reference is used:</P>
606

    
607
<PRE>
608
   &lt;ElementType Name="sales:SalesOrder"/&gt;
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
   &lt;ClassMap&gt;
615
      &lt;ElementType Name="sales:SalesOrder"/&gt;
616
      &lt;ToClassTable&gt;
617
         &lt;Table Name="Sales"/&gt;
618
      &lt;/ToClassTable&gt;
619
      &lt;PropertyMap&gt;
620
         &lt;Attribute Name="SONumber"/&gt;
621
         &lt;ToColumn&gt;
622
            &lt;Column Name="Number"/&gt;
623
         &lt;/ToColumn&gt;
624
      &lt;/PropertyMap&gt;
625
   &lt;/ClassMap&gt;
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
   &lt;EmptyStringIsNull/&gt;
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
   &lt;DateTimeFormats&gt;
652
      &lt;Patterns Date="HH:mm" Time="HH:mm" Timestamp="MMM d, yyyy h:mm"/&gt;
653
   &lt;/DateTimeFormats&gt;
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
   &lt;foo:element1 xmlns="http://foo">
744
   Local name: "element1"
745
   Prefixed name: "foo:element1"
746
   Qualified name: "http://foo^element1"
747

    
748
   &lt;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 &lt;map-file&gt; &lt;xml-file&gt;
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 &lt;map-file&gt; &lt;xml-file&gt; &lt;table-name&gt; &lt;key-value&gt;...
859
</PRE>
860

    
861
<P>where &lt;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 &lt;DTD or XML document&gt;
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 &lt;schema-file&gt;
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