A class indicator determines what class of object each database record represents. A class indicator is only necessary when a persistent class can be extended by other persistent classes. The class indicator is always placed on the base class. Subclasses inherit the class indicator of their parent class.
In Kodo JDO, class indicators extend the base kodo.impl.meta.ClassIndicator class. The concrete class indicators Kodo JDO provides are described in the sections below. By default, the mapping tool uses the in-class-name class indicator for all persistent classes. You can change the default class indicator type with the kodo.jdbc.ClassIndicator configuration property. You can also instruct the mapping tool to use a specific indicator for an individual class with the jdbc-class-ind-name JDO metadata extension.
The in-class-name indicator stores the full class name of persistent objects in a special database column. When you query for objects of certain classes, the indicator appends a SQL IN clause to the end of the query to make sure each record's class name column matches one of target class names.
The in-class-name indicator has the following attributes:
type: in-class-name
column: The name of the column that stores the full class name of each persistent object. The column must be in the class' primary table. This property is required.
Example 7.24. Using an In-Class-Name Indicator
Java class:
public class Magazine
{
... class content ...
}
Schema:
<table name="MAGAZINE">
... primary key columns ...
<column name="JDOCLASS" type="varchar" size="255"/>
... columns for magazine fields ...
</table>
JDO metadata:
<class name="Magazine">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
... class mapping ...
<jdbc-class-ind type="in-class-name" column="JDOCLASS"/>
... field mappings ...
</class>
Mapping information using JDO metadata extensions:
<class name="Magazine">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-class-ind" value="in-class-name">
<extension vendor-name="kodo" key="column" value="JDOCLASS"/>
</extension>
... field metadata ...
</class>
The metadata-value indicator maps persistent classes to symbolic constants stored in a database column. Each class in the inheritance tree using the metadata value indicator uses the jdbc-class-ind-value metadata extension to specify the database value that indicates a row is a member of that class. The extension is required. When you query for objects of certain classes, the indicator appends a SQL IN clause to the end of the query to make sure each record's class indicator column value matches the symbolic constant mapped to one of those classes.
Unlike the in-class-name indicator, this indicator cannot calculate all the subclasses for a given class by examining the database contents. If you use this indicator, you must list all of your persistent classes in the kodo.PersistentClasses property, or make sure all classes in inheritance trees that use this indicator have been referenced in code by the time you perform persistent operations on any of them.
The metadata-value indicator has the following attributes:
type: metadata-value
column: The name of the column that stores the class indicator value for each row. The column must be in the class' primary table. This property is required.
Example 7.25. Using a Metadata-Value Indicator
Java class:
public abstract class Person
{
... class content ...
}
public class Male
extends Person
{
... class content ...
}
public class Female
extends Person
{
... class content ...
}
Schema:
<table name="PERSON">
... primary key columns ...
<column name="SEX" type="char" size="1"/>
... columns for person fields ...
</table>
JDO metadata:
<class name="Person">
<!-- person is abstract, so no class-ind-value required -->
... field metadata ...
</class>
<class name="Male" persistence-capable-superclass="Person">
<extension vendor-name="kodo" key="jdbc-class-ind-value" value="M"/>
... field metadata ...
</class>
<class name="Female" persistence-capable-superclass="Person">
<extension vendor-name="kodo" key="jdbc-class-ind-value" value="F"/>
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Person">
... class mapping ...
<jdbc-class-ind type="metadata-value" column="SEX"/>
... field mappings ...
</class>
<class name="Male">
... class mapping ...
... field mappings ...
</class>
<class name="Female">
... class mapping ...
... field mappings ...
</class>
Mapping information using JDO metadata extensions:
<class name="Person">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-class-ind" value="metadata-value">
<extension vendor-name="kodo" key="column" value="SEX"/>
</extension>
... field metadata ...
</class>
<class name="Male" persistence-capable-superclass="Person">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-class-ind-value" value="M"/>
... field metadata ...
</class>
<class name="Female" persistence-capable-superclass="Person">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-class-ind-value" value="F"/>
... field metadata ...
</class>
The subclass-join indicator determines the class or each database record using outer joins to subclass tables. It does not require a special column to store class information. You can only use this indicator if your database supports outer joins, and if every subclass in your inheritance hierarchy is vertically mapped (see Section 7.6.3, “Vertical Inheritance Mapping”).
The subclass-join indicator has the following attributes:
type: subclass-join
Example 7.26. Using a Subclass-Join Indicator
Java class:
public class Magazine
{
... class content ...
}
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="Magazine">
... field metadata ...
</class>
<class name="Tabloid" persistence-capable-superclass="Magazine">
... field metadata ...
</class>
Mapping information using the mapping XML format:
<class name="Magazine">
... class mapping ...
<jdbc-class-ind type="subclass-join"/>
... field mappings ...
</class>
<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="Magazine">
... class extensions ...
<extension vendor-name="kodo" key="jdbc-class-ind" value="subclass-join"/>
... field metadata ...
</class>
<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 indicators. All class indicators must extend, directly or indirectly, from kodo.jdbc.meta.ClassIndicator.
The jdbc-class-ind-name JDO metadata extension tells the mapping tool which class indicator to install. If you write mappings by hand rather than with the mapping tool, simply specify the full class name of your custom indicator in the type attribute of the mapping XML.
The samples/ormapping directory of the Kodo JDO distribution includes examples of custom mappings.