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.16. 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 inheritance mapping (sometimes referred to as single-table or filtered inheritance) 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.17. 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>
Flat inheritance mapping is the fastest of all inheritance models, since it never requires a join to retrieve a single persistent instance from the database. Similarly, persisting or updating a single persistent instance requires only a single INSERT or UPDATE statement (unlike vertical inheritance mapping).
The larger the inheritance model gets, the "wider" the mapped table gets, in that for every field in the entire inheritance hierarchy, a column must exist in the mapped table. This may have undesirable consequence on the database size, since a deep inheritance hierarchy will result in tables with many columns.
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.5.2, “Non-Standard Joins”.
Example 7.18. 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>
Vertical inheritance mapping results in the most "normalized" database schema, since spurious and redundant data will not exist in any of the tables. As more subclasses are added to the data model over time, the only schema modification that needs to be made is the addition of a corresponding table in the database (rather than having to change the structure of existing tables).
Vertical mappings can be the slowest of all the inheritance models, since retrieving any subclass will require one or more database JOINs, and storing subclasses will require multiple INSERT or UPDATE statements. This is only the case when persistence operations are performed on subclasses; if most operations are performed on the topmost persistent superclass, then a vertical mapping will be as fast as a flat mapping.
When executing a select against a hierarchy that uses vertical inheritance, you must consider how to load subclass data. Section 14.2, “Eager Fetching” describes your options.
The horizontal inheritance mapping (sometimes referred to as distributed or one-table-per-leaf inheritance) is a mapping that maps each concrete class in an inheritance hierarchy to a separate table. A horizontally mapped class does not itself have a table; all the fields in the class will be mapped by the subclasses. Therefore, a horizontally mapped class cannot be directly persisted, only subclasses of the class can be stored in the database. For this reason, it is recommended (but not required) that horizontally mapped classes be declared abstract.
When defining mappings for horizontal subclasses, the field mappings of the superclass' fields are defined in the mapping definition for the subclass. When the mappings are defined in the .mapping format, field mappings for superclasses will be named "package.name.to.SuperClass.fieldName", or, if the superclass is in the same package as the subclass that defines its field, this can be shortened to: "SuperClass.fieldName".
When defining the mappings for a horizontal superclass in a .jdo metadata file, the field mapping definitions must be contained in a special "jdbc-field-mappings" extension element, since the .jdo format disallows <field> tags to be specified for field names that are not declared by the owning class.
As well as having support for a most-derived horizontal mapping, Kodo can also have intermediate classes in any inheritance hierarchy (either vertical or flat) be declared as horizontal. This is convenient for abstract persistent classes for which no table is to be defined.
Example 7.19. Using a Horizontal Mapping
Java class:
public class Magazine
{
private String title;
... class content ...
}
JDO metadata:
<class name="Magazine">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
<jdbc-class-map type="horizontal"/>
</class>
Mapping information using JDO metadata extensions:
<class name="Magazine">
<extension vendor-name="kodo" key="jdbc-class-map" value="horizontal"/>
... field metadata ...
</class>
Java class:
public class Tabloid
extends Magazine
{
private String tabloidType;
... class content ...
}
Schema:
<table name="TABLOID">
<pk column="JDOID"/>
<column name="JDOID" type="bigint"/>
<column name="TABLOID_TYPE" type="varchar" size="255"/>
<column name="TITLE" type="varchar" size="255"/>
... columns for other 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="base" table="TABLOID"/>
... indicator mappings ...
<field name="tabloidType">
<jdbc-field-map type="value" column="TABLOID_TYPE"/>
</field>
<field name="Magazine.title">
<jdbc-field-map type="value" column="TITLE"/>
</field>
... other 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="base">
<extension vendor-name="kodo" key="table" value="TABLOID"/>
</extension>
... indicator extensions ...
<field name="tabloidType">
<extension vendor-name="kodo" key="jdbc-field-map" value="value">
<extension vendor-name="kodo" key="column" value="TABLOID_TYPE"/>
</extension>
</field>
<extension vendor-name="kodo" key="jdbc-field-mappings">
<extension vendor-name="kodo" key="Magazine.title">
<extension vendor-name="kodo" key="jdbc-field-map" value="value">
<extension vendor-name="kodo" key="column" value="TITLE"/>
</extension>
</extension>
</extension>
</class>
Example 7.20. Using a Horizontal Mapping with Application Identity hierarchy
Java class:
public class Magazine
{
private int id;
private String title;
... class content ...
// application identity class for Manager; represented as
// a static inner class for the Managzine class
public static class MagazineID
{
public int id;
public MagazineID ()
{
}
public MagazineID (String idString)
{
id = new Integer (idString).intValue ();
}
public int hashCode ()
{
return id;
}
public boolean equals (Object other)
{
if (other == null || other.getClass () != getClass ())
return false;
return ((MagazineID)other).id == id;
}
}
}
JDO metadata:
<class name="Magazine" objectid-class="Magazine$MagazineID">
<field name="id" primary-key="true"/>
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
<jdbc-class-map type="horizontal"/>
</class>
Mapping information using JDO metadata extensions:
<class name="Magazine" objectid-class="Magazine$MagazineID">
<extension vendor-name="kodo" key="jdbc-class-map" value="horizontal"/>
<field name="id" primary-key="true"/>
... field metadata ...
</class>
Java class:
public class Tabloid
extends Magazine
{
private String tabloidType;
... class content ...
public static class TabloidID
extends Magazine.MagazineID
{
public TabloidID ()
{
super ();
}
public TabloidID (String idString)
{
super (idString);
}
// note that equals() and hashCode() methods in superclass
// are sufficient for application identity hierarchy
}
}
Schema:
<table name="TABLOID">
<pk column="ID"/>
<column name="ID" type="bigint"/>
<column name="TABLOID_TYPE" type="varchar" size="255"/>
<column name="TITLE" type="varchar" size="255"/>
... columns for other tabloid fields ...
</table>
JDO metadata:
<class name="Tabloid" persistence-capable-superclass="Magazine"
objectid-class="Tabloid$TabloidID">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Tabloid">
<jdbc-class-map type="base" table="TABLOID"/>
... indicator mappings ...
<field name="Magazine.id">
<jdbc-field-map type="value" column="ID"/>
</field>
<field name="tabloidType">
<jdbc-field-map type="value" column="TABLOID_TYPE"/>
</field>
<field name="Magazine.title">
<jdbc-field-map type="value" column="TITLE"/>
</field>
... other field mappings ...
</class>
Mapping information using JDO metadata extensions:
<class name="Tabloid" persistence-capable-superclass="Magazine"
objectid-class="Tabloid$TabloidID">
<extension vendor-name="kodo" key="jdbc-class-map" value="base">
<extension vendor-name="kodo" key="table" value="TABLOID"/>
</extension>
... indicator extensions ...
<field name="tabloidType">
<extension vendor-name="kodo" key="jdbc-field-map" value="value">
<extension vendor-name="kodo" key="column" value="TABLOID_TYPE"/>
</extension>
</field>
<extension vendor-name="kodo" key="jdbc-field-mappings">
<extension vendor-name="kodo" key="Magazine.id">
<extension vendor-name="kodo" key="jdbc-field-map" value="value">
<extension vendor-name="kodo" key="column" value="ID"/>
</extension>
</extension>
<extension vendor-name="kodo" key="Magazine.title">
<extension vendor-name="kodo" key="jdbc-field-map" value="value">
<extension vendor-name="kodo" key="column" value="TITLE"/>
</extension>
</extension>
</extension>
</class>
Declaring classes abstract: Kodo does not require that a class that is horizontally mapped be declared abstract. However, it is recommended that these classes not be concrete, since any attempt to persist a superclass that is horizontally mapped will throw a FatalUserException.
Application identity: When a topmost horizontally-mapped superclass uses application identity, one of the following two restrictions must be observed by the application developer:
The primary key values in each of the tables that extend the horizontally mapped superclass much be unique. That is, if MySuperClass declares horizontal mapping, and MySubClass1 and MySubClass2 extend MySuperClass and are mapped to "MY_SUB1" and "MY_SUB2" (respectively), then there can be no row in MY_SUB1 that has a primary key value that exists in MY_SUB2. This is because a call to getObjectById with an application identity instance cannot identify which subclass the ID is associated with.
Rather than having a single application identity class associated with the entire class hierarchy, each subclass declares its own application identity class. The inheritance hierarchy of the application identity classes must exactly match the inheritance hierarchy of the persistent classes they represent. This enables Kodo to unambiguously identify which subclass a specific application identity instance represents.
Relations: Relations to horizontally mapped classes will be treated the same as relations to interfaces or fields of type PersistenceCapable. That is, the relations will be stored as the stringified object id.
An advantage of using a horizontal mapping is that attributes that are common to multiple persistent classes can be defined in the superclass without having to suffer the performance consequences and relational design restrictions of using a vertical mapping. Persisting and modifying instances of subclasses whose superclass uses horizontal mapping is as fast as flat inheritance mapping, since typically only a single INSERT or UPDATE statement will need to be issued.
In addition to the restrictions imposed by using horizontal mappings (see Section 7.6.4.1, “Special considerations when using Horizontal Inheritance Mapping”), queries against the superclass fields of a horizontally-mapped class will require multiple SELECT statements to be executed against the database (one for each concrete subclass). Furthermore, from a relational design standpoint, horizontal mappings are not normalized, since attributes are repeated across different tables.
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.
![[Note]](img/note.gif) | Note |
|---|---|
Kodo's custom class mapping capabilities require a Kodo JDO Enterprise Edition license in order to function. See Chapter 13, Enterprise Edition for details about the Enterprise Edition. | |