Hello,

Here is a simple example of using XML-DBMS. This example uses the
command line, the MapManager and Transfer tools, and the samples in the
samples subdirectory.

Introduction
============

Before you use XML-DBMS, you need to understand what XML-DBMS does.
XML-DBMS does not directly store XML documents in the database. Instead,
it transfers data between XML documents and the database. It does this
according to an object-relational model. That is, it views an XML
document as if it was a serialized object tree and uses an
object-relational mapping between the object tree and the database. The
map language allows you to customize this mapping a little bit.

I strongly suggest you read the paper:

http://www.rpbourret.com/xml/DTDToDatabase.htm

before using XML-DBMS. It will help you understand the general model.
The introduction to section 3 and section 3.1 give you an overview of
how the model works.

XML-DBMS has two different phases: a design phase and a run-time phase.
At design time, you must create a mapping between the XML schema / DTD
and the relational schema. The MapManager tool can help you do this. You
must also set up things like filter files, action files, etc.

At run time, you use the Transfer tool (or call XML-DBMS classes
directly) to actually transfer data between the XML document and the
relational database. Data is transferred according to the map document,
filter file, action file, etc.

Design time
===========
1) Create your XML schema and your relational schema. The MapManager
tool can create a DTD from a relational schema or a relational schema
from a DTD. However, if you use the MapManager tool, you will need to
modify the DTD / relational schema by hand. This is because the
generated schemas are generally very inefficient. For example, the
MapManager tool cannot guess which elements or attributes in a DTD
contain primary key information.

To create a relational schema from orders.dtd, you would use the
following command:

c:\xmldbms\samples>java org.xmlmiddleware.xmldbms.tools.MapManager
File1=parser.props File2=db.props Input=DTD DTDFile=orders.dtd
Output=SQL SQLFile=orders.sql

parser.props and db.props contain information about the XML parser and
database you will be using. You can modify the files in the samples
directory for your system.

The Input keyword tells the MapManager what you are starting from. The
possible values are Map, DTD, and Database. In this case, we are
starting with a DTD and want to generate a relational schema (SQL file).

The Output keyword tell MapManager what we want to generate. The
possible values are Map, DTD, and SQL.

The DTDFile and SQLFile keywords give the names of those files. We need
a DTDFile because Input is DTD. We need SQLFile because Output is SQL.

After you run the MapManager, you will need to modify the SQL file by
hand to make any necessary corrections. For example, you will need to
change the data types in the CREATE TABLE statements to the correct data
types (instead of VARCHAR(254)) and you will probably need to change the
PRIMARY KEY clauses to use primary key information from the XML
document. (MapManager assumes you are using database-generated keys.)

For our sample, your completed files should look like orders.sql.

2) Create a mapping from the XML schema to the relational schema. This
is done with a map document. Normally, you must write this document by
hand. If you have a complex schema, this will be a lot of work. For an
overview of the mapping language, see section 4.3 of the XML-DBMS 1.0
readme [1]. The version 2.0 mapping language is a little bit different,
but the ideas are the same. For an example of a complete map document,
see orders.map in the samples directory.

Your relational schema and your XML schema must have roughly the same
structure. If they have very different structures, you will need to
create an XML schema that has the same structure as the relational
schema. You will then need to write an XSLT transformation to transform
XML documents between your original DTD and the DTD that matches the
relational schema. That is:

XML document (original DTD)
|
| XSLT
V
XML document (new DTD)
|
| XML-DBMS
V
Database

You can also use MapManager to help you create the mapping. This will
work only if you have a DTD (but not a relational schema) or a
relational schema (but not a DTD). If you already have a relational
schema and a DTD, you will need to create the mapping by hand.

For example, to generate both a relational schema and a map document,
use the following command.

c:\xmldbms\samples>java org.xmlmiddleware.xmldbms.tools.MapManager
File1=parser.props File2=db.props Input=DTD DTDFile=orders.dtd
Output1=Map MapFile=orders.map Output2=SQL SQLFile=orders.sql

Note that we use the Output1 and Output2 keywords because we want both a
map and a relational schema. We also add the MapFile keyword to give the
name of the map file. As before, you will need to modify the map
document and SQL schema by hand to get the mapping you want.

For our sample, your completed files should look like orders.map and
orders.sql.

3) Create an actions document. This specifies what actions you want to
take for each element mapped as a class -- that is, mapped to a table
instead of a column. For example, see orders1.act. This says that, by
default, you simply insert data into the database. There are two
exceptions: for the Part and Customer elements, first check if the data
is in the database. If it is, update it. If it is not, insert it.

You only need an actions document to insert, update, or delete data. You
do not need an actions document to transfer data from the database to XML.

4) Create a filter document. This specifies what data you want to
retrieve from the database. You only need a filter document if you are
transferring data from the database to XML. For example, see orders.ftr.
This says to transfer all data from the Orders table (condition is 0=0).

Run time
========
To transfer data, it is easiest to use the Transfer tool. You will pass
the parser and database information, the map document, the actions
and/or filter documents, and the XML document. You will also specify
what to do -- for example, store data from a document. For example:

c:/xmldbms/samples>java org.xmlmiddleware.xmldbms.tools.Transfer
File1=parser.props File2=db.props Method=StoreDocument
MapFile=orders.map XMLFile=orders.xml ActionFile=orders.act

As before parser.props and db.props provide parser and database information.

The Method keyword specifies what you want to do. In this case,
StoreDocument means you want to transfer data from XML to the database.
(This includes updating data. You specify whether to insert or update
data in the actions document.) Other legal values are
RetrieveDocumentByFilter, RetrieveDocumentBySQL, and DeleteDocument.

The MapFile, XMLFile, and ActionFile keywords give the names of the map,
XML, and action documents.

I hope this helps. Please write if you have specific problems.

-- Ron

[1] http://www.rpbourret.com/xmldbms/readme1x.htm

meisam sarabadani wrote:

> Hi, I am very new to XML-DBMS
>
> but I really do need it, I have read its documentations from beginners to
advances, I have understood only a few things.
>
> but I still do not know how to insert an XML document or DTD to RDBMS? :(((
this is part of my project that i should submit it next week, i have even
checked he samples, I saw many action and props files, please give me some steps
to start the insertion,
>
> here is my problem:
>
> I need to insert a DTD to relational tables. would you give me the steps of
doing this, but more clear than the its own documentation, I did not understand
the documentation about ManagerTool,would you please help me, I really need
somebody to guide me from the beginning.