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