Value handlers make it trivial to map any type that you can break down into one or more simple values. All value handlers implement the kodo.jdbc.meta.ValueHandler interface. Rather than give synthetic examples of value handlers, Kodo provides the source to most of the built-in handlers in the src/kodo/jdbc/meta/strats directory of your Kodo distribution. Use these functional implementations as examples when you create your own value handlers.

Note that value handlers are not only simple to write, but are highly reusable. For example, imagine that you create a handler for java.awt.Point values. You can not only use this handler to map fields of type Point, but also to map Collections or Maps of Points with no additional work.

Kodo interacts with persistent fields through the kodo.jdbc.meta.FieldStrategy interface. You can implement this interface yourself to create a custom field strategy, or extend one of the existing abstract or concrete strategies in the kodo.jdbc.meta.strats package. Creating a custom field strategy is more difficult than writing a custom value handler, but gives you more freedom in how you interact with the database. Section 1.3.5, “Custom Mappings” describes custom mapping samples that ship with Kodo.

Kodo gives you two ways to configure your custom field mappings. The FieldStrategies property of the built-in MappingDefaults implementations allows you to globally associate field types with their corresponding custom value handler or strategy. Kodo will automatically use your custom strategies when it encounters a field of the associated type. Kodo will use your custom value handlers whenever it encounters a field, collection element, map key, or map value of the associated type. Section 7.4, “Mapping Defaults” described mapping defaults in detail.

Your other option is to explicitly install a custom value handler or strategy on a particular field. To do so, specify the full name of your implementation class in the proper mapping metadata extension. Kodo JPA includes the org.apache.openjpa.persistence.jdbc.Strategy, kodo.persistence.jdbc.ElementStrategy, and kodo.persistence.jdbc.KeyStrategy annotations. Kodo JDO recognizes jdbc-strategy, jdbc-element-strategy, jdbc-key-strategy, and jdbc-value-strategy field extension keys. You can configure the named strategy or handler's bean properties in these extensions using Kodo's plugin format (see Section 2.4, “Plugin Configuration”).

The example below installs a custom strategy on the coverImage field, uses a custom value handler for the primaryInfoStruct field, and uses the same value handler for the elements of the secondaryInfoStructs collection.

import kodo.persistence.jdbc.*;
import org.apache.openjpa.persistence.*;
import org.apache.openjpa.persistence.jdbc.*;

@Entity
public class Magazine
{
    @Persistent
    @Strategy("org.mag.mapping.ImageStrategy")
    @Column(name="IMG")
    private Image coverImage;
 
    @Persistent
    @Strategy("org.mag.mapping.InfoStructHandler")
    @Columns({
        @Column(name="DATA1"),
        @Column(name="DATA2"),
        @Column(name="DATA3")
    })
    private InfoStruct primaryInfoStruct;

    @PersistentCollection
    @ContainerTable(name="SEC_STRUCTS", joinColumns=@XJoinColumn(name="MAG_ID"))
    @ElementStrategy("org.mag.mapping.InfoStructHandler")
    @ElementColumns({
        @ElementColumn(name="DATA1"),
        @ElementColumn(name="DATA2"),
        @ElementColumn(name="DATA3")
    })
    private Collection<InfoStruct> secondaryInfoStructs;

    ...
}

<?xml version="1.0"?>
<orm>
    <package name="org.mag">
        <class name="Magazine" table="MAG">
            <field name="coverImage" column="IMG">
                <extension vendor-name="kodo" key="jdbc-strategy"
                    value="org.mag.mapping.ImageStrategy"/>
            </field>
            <field name="primaryInfoStruct">
                <column name="DATA1"/>
                <column name="DATA2"/>
                <column name="DATA3"/>
                <extension vendor-name="kodo" key="jdbc-strategy"
                    value="org.mag.mapping.InfoStructHandler"/>
            </field>
            <field name="secondaryInfoStructs" table="SEC_STRUCTS">
                <join column="MAG_ID"/>
                <element>
                    <column name="DATA1"/>
                    <column name="DATA2"/>
                    <column name="DATA3"/>
                </element>
                <extension vendor-name="kodo" key="jdbc-element-strategy"
                    value="org.mag.mapping.InfoStructHandler"/>
            </field>
            ...
        </class>
    </package>
</orm>