7.4. Mapping File XML Format
Prev | Chapter 7. Object-Relational Mapping | Next

## 7.4. Mapping File XML Format

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:

Example 7.15. Basic Structure of Mapping Documents

    <?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.

Example 7.16. Complete Mapping Document

    <?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>

Prev | Up | Next
7.3. Mapping Factory | Home | 7.5. Mapping Notes