Several mapping factories store their mapping data in XML. The mapping tool also serializes mapping data to and from XML during its import and export operations. This section covers the common XML format used by all of these components.

Below we present the Document Type Definition (DTD) for the XML mapping format. Note that this DTD is not valid, because in many places we declare an ATTLIST with a value of ANY, which is not legal DTD syntax. We do this to indicate that the corresponding element can have any additional attributes. Which attributes are used depends on the type of the mapping. Thus, XML mapping documents are not validated by Kodo JDO.

<!ELEMENT mapping (package)+>

<!ELEMENT package (class)+>
<!ATTLIST package name CDATA #REQUIRED>

<!ELEMENT class (jdbc-class-map, (jdbc-version-ind)?, (jdbc-class-ind)?, 
   (field)*)>
<!ATTLIST class name CDATA #REQUIRED>

<!ELEMENT jdbc-class-map EMPTY>
<!ATTLIST jdbc-class-map type CDATA #REQUIRED>
<!ATTLIST jdbc-class-map ANY>

<!ELEMENT jdbc-version-ind EMPTY>
<!ATTLIST jdbc-version-ind type CDATA #REQUIRED>
<!ATTLIST jdbc-version-ind ANY>

<!ELEMENT jdbc-class-ind EMPTY>
<!ATTLIST jdbc-class-ind type CDATA #REQUIRED>
<!ATTLIST jdbc-class-ind ANY>

<!ELEMENT field (jdbc-field-map)*>
<!ATTLIST field name CDATA #REQUIRED>

<!ELEMENT jdbc-field-map (field)*>
<!ATTLIST jdbc-class-map type CDATA #REQUIRED>
<!ATTLIST jdbc-class-map ANY>

As you can see, the format of mapping files is closely aligned with the format of JDO metadata files. The basic structure is the same:

<?xml version="1.0"?>
<mapping>
    <package name="org.mag">
        <class name="Magazine">
            ... class-level data ...
            <field name="isbn">
                ... field-level data ...
            </field>
            <field name="title">
                ... field-level data ...
            </field>
            <field name="articles">
                ... field-level data ...
            </field>
        </class>
        ... other classes ...
    </package>
    ... other packages ...
</mapping>

Other than package, class, and field names, however, mapping documents do not repeat any information that is already found in the JDO metadata. You do not specify things like the identity type of classes, or the element type of collection fields.

Mapping documents, do, however, contain extra information not present in JDO metadata. At the class level, they contain a required jdbc-class-map element describing how the class is mapped to the database. The class element can also have optional jdbc-version-ind and jdbc-class-ind child elements describing the version indicator and class indicator mappings for the class, respectively. All of these elements have a required type attribute specifying the short type name of the mapping. You can also supply the full class name of a custom mapping type in this attribute. Class mappings, version indicators, and class indicators are covered in later sections of this chapter.

Each field element of a mapping document represents a member field, and all managed fields in each class must be listed. Each field contains a single jdbc-field-map element. The attributes of this element describe how the field maps to the database. Like the jdbc-class-map, jdbc-version-ind, and jdbc-class-ind elements, the jdbc-field-map element requires a type attribute. This attribute specifies the short type name of the mapping, or the full class name of a custom mapping. Field mappings are also discussed in depth later in this chapter.

	Note
	In mappings for embedded objects, the jdbc-field-map elements have field child elements for the persistent fields of the embedded type. See the description of the embedded one-to-one mapping.

<?xml version="1.0"?>
<mapping>
    <package name="org.mag">
        <class name="Magazine">
            <jdbc-class-map type="base" table="MAGAZINE" pk-column="JDOID"/>
            <jdbc-version-ind type="version-number" column="JDOVERSION"/>
            <jdbc-class-ind type="in-class-name" column="JDOCLASS"/>
            <field name="isbn">
                <jdbc-field-map type="value" column="ISBN"/>
            </field>
            <field name="title">
                <jdbc-field-map type="value" column="TITLE"/>
            </field>
            <field name="articles">
                <jdbc-field-map type="one-many" table="ARTICLE" 
                    ref-column.JDOID="MAGAZINE_ID"/>
            </field>
        </class>
    </package>
</mapping>