7.5. Class Mapping
Prev | Chapter 7. Object-Relational Mapping | Next

## 7.5. Class Mapping

A class mapping describes how a class maps to the database. It typically controls the primary table for the class and how the class is linked to its superclass data, if any. For classes using datastore identity, the class mapping also manages the primary key column for the class.

In Kodo JDO, class mappings extend the base `kodo.jdbc.meta.ClassMapping` class. The concrete class mappings Kodo JDO provides are described in the sections below. By default, the mapping tool uses the base class mapping for all persistent classes without a persistence-capable superclass, and the flat class mapping for all persistent subclasses. You can change the default subclass mapping type with the `kodo.jdbc.SubclassMapping` configuration property. You can also instruct the mapping tool to use a specific mapping for an individual class with the `jdbc-class-map-name` JDO metadata extension.

### 7.5.1. Base Mapping

The base class mapping is reserved for persistent classes that do not extend from any other persistent class. The base class mapping has the following attributes:

- `type`: base

- `table`: The name of the table in which the primary key data is stored for each record of this class. This property is required.

- `pk-column`: The name of the primary key column for classes that use datastore identity. This property is not used for classes with application identity. The named column must be of some numeric type, as Kodo JDO uses Java `long` values for datastore identities.

Example 7.12. Using a Base Mapping

    Java class:

    public class Magazine
    {
        ... class content ...
    }

    Schema:

    <table name="MAGAZINE">
        <column name="JDOID" type="bigint"/>
        <pk column="JDOID"/>
        ... columns for magazine fields ...
    </table>

    JDO metadata:

    <class name="Magazine">
        ... field metadata ...
    </class>

    Mapping information using the mapping XML format:

    <class name="Magazine">
        <jdbc-class-map type="base" table="MAGAZINE" pk-column="JDOID"/>
        ... indicator mappings ...
        ... field mappings     ...
    </class>

    Mapping information using JDO metadata extensions:

    <class name="Magazine">
        <extension vendor-name="kodo" key="jdbc-class-map" value="base">
            <extension vendor-name="kodo" key="table" value="MAGAZINE"/>
            <extension vendor-name="kodo" key="pk-column" value="JDOID"/>
        </extension>
        ... indicator extensions ...
        ... field metadata       ...
    </class>

### 7.5.2. Flat Mapping

The flat class mapping is a mapping for persistent subclasses that stores their fields in the same table as the parent class. The flat class mapping has the following attributes:

- `type`: flat

Example 7.13. Using a Flat Mapping

    Java class:

    public class Tabloid
        extends Magazine
    {
        ... class content ...
    }

    Schema:

    <table name="MAGAZINE">
        ... primary key columns         ...
        ... columns for magazine fields ...
        ... columns for tabloid fields  ...
    </table>

    JDO metadata:

    <class name="Tabloid" persistence-capable-superclass="Magazine">
        ... field metadata ...
    </class>

    Mapping information using the mapping XML format:

    <class name="Tabloid">
        <jdbc-class-map type="flat"/>
        ... indicator mappings ...
        ... field mappings     ...
    </class>

    Mapping information using JDO metadata extensions:

    <class name="Tabloid" persistence-capable-superclass="Magazine">
        <extension vendor-name="kodo" key="jdbc-class-map" value="flat"/>
        ... indicator extensions ...
        ... field metadata       ...
    </class>

### 7.5.3. Vertical Mapping

Subclasses whose derived fields are in a different table than their superclass fields use a vertical class mapping. The vertical class mapping has the following attributes:

- `type`: vertical

- `table`: The name of the table in which the derived fields of the class are stored. This property is required.

- `ref-column.<pk column>`*: Kodo JDO must be able to join this class' table to the table of the parent class. Each `ref-column` attribute joins a column in this class' table to the corresponding column in the parent class' table. See the previous discussion of join attributes for details on joins.

- `ref-constant.<column>`*: Similar to the `ref-column` attribute, but used when the join relies on a column in the joined-to table having a constant value. For more information on constant joins, see Section 7.4.2, “Non-Standard Joins”.

Example 7.14. Using a Vertical Mapping

    Java class:

    public class Tabloid
        extends Magazine
    {
        ... class content ...
    }

    Schema:

    <table name="MAGAZINE">
        <column name="JDOID" type="bigint"/>
        <pk column="JDOID"/>
        ... columns for magazine fields ...
    </table>

    <table name="TABLOID">
        <column name="MAG_ID" type="bigint"/>
        <fk to-table="MAGAZINE">
            <join column="MAG_ID" to-column="JDOID"/>
        </fk>
        ... columns for tabloid fields ...
    </table>

    JDO metadata:

    <class name="Tabloid" persistence-capable-superclass="Magazine">
        ... field metadata ...
    </class>

    Mapping information using the mapping XML format:

    <class name="Tabloid">
        <jdbc-class-map type="vertical" table="TABLOID" ref-column.JDOID="MAG_ID"/>
        ... indicator mappings ...
        ... field mappings     ...
    </class>

    Mapping information using JDO metadata extensions:

    <class name="Tabloid" persistence-capable-superclass="Magazine">
        <extension vendor-name="kodo" key="jdbc-class-map" value="vertical">
            <extension vendor-name="kodo" key="table" value="TABLOID"/>
            <extension vendor-name="kodo" key="ref-column.JDOID" value="MAG_ID"/>
        </extension>
        ... indicator extensions ...
        ... field metadata       ...
    </class>

### 7.5.4. Custom Class Mapping

Kodo JDO allows you to create your own class mappings. A custom class mapping can override any or all of the CRUD operations for objects of the class: Create, Retrieve, Update, Delete. All mappings must extend, directly or indirectly, from `kodo.jdbc.meta.ClassMapping`.

The `jdbc-class-map-name` JDO metadata extension tells the mapping tool which class mapping to install. If you write mappings by hand rather than with the mapping tool, simply specify the full class name of your custom mapping in the `type` attribute of the mapping XML.

The `samples/ormapping` directory of the Kodo JDO distribution includes examples of custom mappings.

Prev | Up | Next
7.4. Mapping Notes | Home | 7.6. Version Indicator