Metacat

<!--

   No copyright, no warranty; use as you will.

   Written by Ronald Bourret, Technical University of Darmstadt, 1998-9

-->

<!--

   XML-DBMS is a system for transferring data between XML documents

   and relational databases. It views an XML document as a tree of

   objects and then uses an object-relational mapping to map these

   objects to a relational database.

   Generally, element types are viewed as classes, and attributes and

   PCDATA are viewed as properties of those classes. However, element

   types can also be viewed as properties of their parent element

   type. Although this is most useful when an element type contains

   only PCDATA, 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.

   (Note that the tree of objects is *not* the DOM. This is because

   the DOM models the document itself, not the data in that document.)

   The XML-DBMS mapping language, which is described in this DTD,

   allows users to:

   a) Declare how element types are to be viewed (as classes or

      properties),

   b) Declare which subelements, attributes, and PCDATA are to be

      viewed as properties of a given element type-as-class (unmapped

      XML structures are ignored), and

   c) State how to map the resulting classes and properties to the

      database.

   The resulting object-relational mapping maps classes to tables and

   properties to either columns in those tables or to subtables. (The

   latter is useful, for example, for storing BLOB properties

   separately.) Inter-class relationships are mapped as candidate key

   / foreign key relationships. The mapping can also state whether to

   preserve information about the order in which subelements and

   PCDATA occur within their parent, which is generally important in

   document-centric XML documents and unimportant in data-centric XML

   documents.

-->

<!-- 

   The XMLDBMS element type is the root element type of the

   mapping document.

 -->

<!ELEMENT XMLToDBMS (Options*, Maps)>

<!ATTLIST XMLToDBMS

          Version CDATA #FIXED "1.0">

<!--

   Options is simply a container to hold the various options you

   can set.

-->

<!ELEMENT Options (EmptyStringIsNull?, DateTimeFormats?, Namespace*)>

<!--

   The EmptyStringIsNull element states how empty strings in an

   XML document correspond to NULLs in the database. Technically,

   NULL means that there is no value and is distinct from an empty

   string. In an XML document, this corresponds to an optional

   element or attribute being missing, as opposed to its being

   present and having an empty string as its value (this includes

   empty elements).

   However, many XML users are likely to think of empty strings

   as NULLs. EmptyStringIsNull allows XML-DBMS users to handle

   this situation. If it is present, empty strings are treated

   the same as NULLs; if it is absent, empty strings are treated

   as strings.

   The following table shows how NULL values and empty strings in

   the database are transferred to missing elements/attributes and

   empty strings in the XML document and vice versa.

                                     Transfer Direction

                          _______________________________________

       EmptyStringIsNull |                   |                   |

          element is:    |  DBMS  =>  XML    |    XML  =>  DBMS  |

      ___________________|___________________|___________________|

     |                   |                   |                   |

     |                   | NULL   => missing | missing => NULL   |

     |    not present    |                   |                   |

     |                   | empty  => empty   | empty   => empty  |

     |                   | string    string  | string     string |

     |___________________|___________________|___________________|

     |                   |                   |                   |

     |                   | NULL   => empty   | missing => NULL   |

     |                   |           string  |                   |

     |     present       |                   |                   |

     |                   | empty  => empty   | empty   => NULL   |

     |                   | string    string  | string            |

     |___________________|___________________|___________________|

   Note that EmptyStringIsNull applies only to elements and

   attributes mapped as properties. (An empty element-as-class with

   no attributes results in a row of all NULLs in the database.) 

-->

<!ELEMENT EmptyStringIsNull EMPTY>

<!--

   The DateTimeFormats element and its subelements specify the formats

   used to parse dates, times, and timestamps. The information specified

   here is used to construct one of Java's date formatting objects -

   either a java.text.DateFormat or a java.text.SimpleDateFormat.

   The value of the Language attribute must be a valid ISO Language Code.

   These are defined by ISO-639 and are available on the Web. For example,

   try:

      http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt 

   The value of the Country attribute must be a valid ISO Country Code.

   These are defined by ISO-3166 and are also available on the Web. For

   example, try:

      http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1.html

   The value of Date, Time, and Timestamp attributes must be either one

   of the keywords FULL, LONG, MEDIUM, or SHORT, whose formats are

   described in the documentation for DateFormat, or a formatting

   pattern as defined in the documentation for SimpleDateFormat. Which

   format is used depends on the data type of the target column. (If

   values are not being formatted correctly, be sure to check how the

   JDBC driver maps the type of the target column. For example,

   MS Access only supports TIMESTAMP columns.)

   If an element is missing, the default value is used. For example, if

   the Locale element is missing, the default locale is used. If the

   DateTimeFormats element is missing, the default locale and format

   are used. Note that Locale is used only if Date, Time, or Timestamp

   is present.

-->

<!ELEMENT DateTimeFormats (Locale?, Patterns)>

<!ELEMENT Locale EMPTY>

<!ATTLIST Locale

          Language NMTOKEN #REQUIRED

          Country NMTOKEN #REQUIRED>

<!ELEMENT Patterns EMPTY>

<!ATTLIST Patterns

          Date CDATA #IMPLIED

          Time CDATA #IMPLIED

          Timestamp CDATA #IMPLIED>

<!--

   Namespace elements give URIs and their associated prefixes. These

   are used as follows:

   a) In the mapping document, prefixes identify which namespace an

      element or attribute belongs to. They can be used in the Name

      attribute of the ElementType and Attribute element types.

   b) When transferring data from an XML document to the database,

      namespace URIs are used to identify elements and attributes in

      that document. The XML document can use different prefixes than

      are used in the mapping document.

   c) When transferring data from the database to an XML document,

      namespace URIs and prefixes are used to prefix element and

      attribute names in that document.

   Namespace elements are not required. If they are used, the same URI

   or prefix cannot be used more than once. Zero-length prefixes ("")

   are not currently supported.

-->

<!ELEMENT Namespace EMPTY>

<!ATTLIST Namespace

          Prefix NMTOKEN #REQUIRED

          URI CDATA #REQUIRED>

<!ELEMENT Maps (IgnoreRoot*, ClassMap+)>

<!--

   IgnoreRoot elements instruct the transfer software to ignore the

   root element of the XML document (when transferring data from an

   XML document to the database) or to construct an enclosing root

   element (when transferring data from the database to an XML

   document). This is useful when a document contains multiple,

   unrelated instances of a particular class.

   For example, suppose a document contains multiple sales orders:

   each sales order is represented by a SalesOrder element and a

   single Orders element serves as the root of the document. If the

   sales orders are unrelated - that is, no information is stored in

   the database about which sales orders are in this particular

   document - then the root element of the document (Orders) should

   be ignored.

   The ElementType sub-element of IgnoreRoot identifies the root

   element type to be ignored. A given map can identify multiple roots

   that are to be ignored.

   The PseudoRoot sub-elements of IgnoreRoot identify the mapped

   children of the ignored root. Each is identified by its ElementType

   and must be mapped separately in a ClassMap element. CandidateKey

   (optional) gives the candidate key in the table to which the

   pseudo-root element is mapped and OrderColumn (optional) gives the

   column containing information about the order in which the

   pseudo-root occurs in the actual root.

-->

<!ELEMENT IgnoreRoot (ElementType, PseudoRoot+)>

<!ELEMENT PseudoRoot (ElementType, CandidateKey?, OrderColumn?)>

<!--

   ClassMap elements state that an element type (identified by the

   ElementType subelement) is to be treated as a class. They also

   provide information about the properties of that class (PropertyMap

   subelements), any classes that are related to the class

   (RelatedClass subelements), and how to map that class to the

   database (ToRootTable and ToClassTable subelements).

   A root table is any table that can be used as the top-level table

   when extracting data from the database. The CandidateKey and

   OrderColumn subelements give the columns that are used in the

   WHERE and ORDER BY clauses when extracting data. The root element

   type must be mapped as either ToRootTable or IgnoreRoot.

-->

<!ELEMENT ClassMap (ElementType,

                    (ToRootTable | ToClassTable),

                    PropertyMap*, RelatedClass*)>

<!ELEMENT ToRootTable (Table, CandidateKey?, OrderColumn?)>

<!ELEMENT ToClassTable (Table)>

<!--

   PropertyMap elements state that an attribute, PCDATA, or element

   type is to be treated as a property. The property is identified by

   the Attribute, PCDATA, or ElementType subelement and belongs to the

   class in whose ClassMap the PropertyMap is nested.

   Attributes and PCDATA can be properties only of their parent

   element type-as-class. An element type can be a property of any

   parent element type. Thus, an element type can be declared to be a

   property of more than one element type-as-class.

   Property values are stored in columns. These can be either in the

   class table (ToColumn) or in a separate table (ToPropertyTable). In

   the latter case, Table identifies the property table, and

   CandidateKey and ForeignKey identify the keys used to join the two

   tables.

   The OrderColumn subelement designates the column in which the

   system stores order information. For more information, see

   OrderColumn below.

-->

<!ELEMENT PropertyMap ((Attribute | PCDATA | ElementType),

                       (ToColumn | ToPropertyTable),

                       OrderColumn?)>

<!ELEMENT ToColumn (Column)>

<!ELEMENT ToPropertyTable (Table, CandidateKey, ForeignKey, Column)>

<!ATTLIST ToPropertyTable

          KeyInParentTable (Candidate | Foreign) #REQUIRED>

<!--

   RelatedClass elements describe classes that are related to

   the class being defined. In class terms, you can think of

   this as meaning that a property is added to the class being

   defined that points to the related class. In XML terms, this

   means that the element type for the related class is a child

   of the element type for the class being defined.

   (Note that the term "child class" could have been used here,

   but wasn't due to the potential for confusion with parent/

   child table relationships, parent/child element

   relationships, and class inheritance relationships.)

   For example, in the following XML document, if the element

   types <A> and <B> are mapped as classes, then <B> needs to

   be defined as a related class of <A>.

      <A>

         <property_A1>123</property_A1>

         <property_A2>abcde</property_A2>

         <B>

            <property_B1>123</property_B1>

            <property_B2>abcde</property_B2>

         </B>

      </A>

   The RelatedClass element specifies the element type of the

   related class, the candidate and foreign keys used to join

   the tables for the two classes, and the name of the column

   (if any) which contains the order in which the elements for

   the related class appear in the class being defined.

-->

<!ELEMENT RelatedClass (ElementType,

                        CandidateKey, ForeignKey,

                        OrderColumn?)>

<!ATTLIST RelatedClass

          KeyInParentTable (Candidate | Foreign) #REQUIRED>

<!--

   The CandidateKey and ForeignKey elements describe the keys used to

   join two tables: either two class tables or a class table and a

   property table. Which key occurs in the parent table is declared in

   the RelatedClass or ToPropertyTable element with the

   KeyInParentTable attribute.

   In addition, the CandidateKey element is used to identify the

   columns used to identify rows when extracting data from the root

   table.

   The Generate attribute tells the system whether to generate the

   candidate key. If the key is generated, the user must provide a

   class that generates the key; for more information, see:

      de.tudarmstadt.ito.xmldbms.KeyGenerator

      de.tudarmstadt.ito.xmldbms.helpers.KeyGeneratorImpl

   If the key is not generated, other properties must be mapped to

   the key columns.

-->

<!ELEMENT CandidateKey (Column+)>

<!ATTLIST CandidateKey

          Generate (Yes | No) #REQUIRED>

<!ELEMENT ForeignKey (Column+)>

<!--

   ElementType, Attribute, and PCDATA elements are used to identify

   the corresponding XML structures.

   The MultiValued attribute of the Attribute element type states

   whether individual tokens in an attribute are separate values

   (NMTOKENS, IDREFS, and ENTITIES attributes) or a single value

   (CDATA, ID, IDREF, ENTITY, and NMTOKEN attributes).

-->

<!ENTITY % XMLName "Name NMTOKEN #REQUIRED">

<!ELEMENT ElementType EMPTY>

<!ATTLIST ElementType

          %XMLName;>

<!ELEMENT Attribute EMPTY>

<!ATTLIST Attribute

          %XMLName;

          MultiValued (Yes | No) "No">

<!ELEMENT PCDATA EMPTY>

<!--

   Table, Column, and OrderColumn names are used to identify the

   corresponding XML structures. Table and column names must follow

   the naming conventions used in the database. For example, if

   column names are stored in upper case in the database, then they

   must be specified in upper case in the mapping document. Table

   names may be qualified with catalog and schema names. Column names

   must not be qualified; the table to which they belong is determined

   from context (see below). Column names must not be quoted; the system

   quotes them before using them in SQL statements.

   When transferring data from the database to an XML document, the

   special table name "Result Set" is used when the root table is a

   result set.

   The table to which a column belongs is determined as follows:

   Column element in:        Column occurs in:

   __________________        ________________________________________

   ToColumn                  Class table

   ToPropertyTable           Property table

   CandidateKey              Determined by KeyInParentTable attribute

   ForeignKey                Determined by KeyInParentTable attribute

   OrderColumn element in:   Column occurs in:

   __________________        ________________________________________

   PseudoRoot                Class table of pseudo-root element

   PropertyTable             Class table

                               (if property mapped as ToColumn)

                             Same table as foreign key

                               (if property mapped as ToPropertyTable)

   RelatedClass              Same table as foreign key

   Order columns are used to store information about the order in

   which elements and PCDATA occur in their parent element, as well as

   the order of values in multi-valued attributes (IDREFS, NMTOKENS,

   and ENTITIES).

   Storing order information is optional; if it is not stored, there

   is no guarantee that order will be preserved in a round trip from

   an XML document to the database and back again. (Note that nesting

   is preserved; that is, subelements and PCDATA always occur in the

   correct parent.)

   The Generate attribute of the OrderColumn element tells the system

   whether to generate order information or not. (The presence or

   absence of the OrderColumn element tells the system whether to use

   order information.) If order information is generated, the order

   column must be of type java.sql.Types.Integer. If order information

   is not generated, another property must be mapped to the order

   column.

-->

<!ENTITY % DatabaseName "Name CDATA #REQUIRED">

<!ELEMENT Table EMPTY>

<!ATTLIST Table

          %DatabaseName;>

<!ELEMENT Column EMPTY>

<!ATTLIST Column

          %DatabaseName;>

<!ELEMENT OrderColumn EMPTY>

<!ATTLIST OrderColumn

          %DatabaseName;

          Generate (Yes | No) #REQUIRED>