5.4. Migrating from Kodo 3.x to Kodo 4.0

5.4.1. API Compatibility
5.4.2. Metadata and Mappings
5.4.3. Configuration

Kodo 4 is a major release. Kodo 4 supports both the JPA and JDO specifications on top of the same persistence kernel. As such, Kodo's package structure and configuration options have changed to reflect its kernel-based architecture. Additionally, Kodo 4 incorporates the latest JDO specification's relational mapping format, superceding Kodo 3's proprietary mapping options.

Kodo 4 does include backwards compatibility for Kodo 3's primary interfaces, and for Kodo 3's metadata and mapping files. The following sections describe how to use these compatibility features.

5.4.1. API Compatibility

In addition to the standard JDO APIs, the following Kodo 3 interfaces are available in Kodo 4. The Kodo 4 equivalent of each interface is shown in parentheses.

  • kodo.runtime.KodoPersistenceManagerFactory (kodo.jdo.KodoPersistenceManagerFactory)

  • kodo.runtime.KodoPersistenceManager (kodo.jdo.KodoPersistenceManager)

  • kodo.runtime.KodoExtent (kodo.jdo.KodoExtent)

  • kodo.runtime.KodoHelper (kodo.jdo.KodoJDOHelper)

  • kodo.runtime.FetchConfiguration (kodo.jdo.KodoFetchPlan)

  • kodo.runtime.SequenceGenerator (javax.jdo.datastore.Sequence)

  • kodo.query.KodoQuery (kodo.jdo.KodoQuery)

  • kodo.jdbc.runtime.JDBCPersistenceManagerFactory (kodo.jdo.PersistenceManagerFactoryImpl)

  • kodo.jdbc.runtime.JDBCFetchConfiguration (kodo.jdo.jdbc.JDBCFetchPlan)

To continue to use these Kodo 3 interfaces in your application, simply keep your javax.jdo.PersistenceManagerFactoryClass property set to its Kodo 3 value of kodo.jdbc.runtime.JDBCPersistenceManagerFactory. These backwards-compatibility interfaces even extend the corresponding Kodo 4 components, so you can access any new Kodo 4 APIs or slowly migrate portions of your code to use Kodo 4 rather than Kodo 3 interfaces.


If you bootstrap your Kodo 3 application using something other than the JDOHelper or KodoHelper bootstrapping methods, you will have to manually constrct a kodo.jdbc.runtime.JDBCPersistenceManagerFactory from a Kodo 4 factory.

5.4.2. Metadata and Mappings

To use Kodo 3 metadata and mapping files, you must set the following configuration properties:

  • kodo.MetaDataFactory: kodo3

  • kodo.jdbc.MappingFactory: file if you use .mapping files, metadata if you use mapping metadata extensions, or db if you use a database table to hold your mapping data.


If you'd like to switch to Kodo 4 metadata and mappings at any time, you can do so using the mapping tool. Section 7.5.1, “Importing and Exporting Mapping Data” covers this process in detail. Be sure to pass the -meta true flag to the tool to migrate your metadata along with your mappings.

Kodo 3 used a table called JDO_SEQUENCE to generate sequence numbers by default. Kodo 4 uses a table called OPENJPA_SEQUENCE_TABLE instead. To continue using your JDO_SEQUENCE table, set the following property:

  • kodo.Sequence: Table=JDO_SEQUENCE

Finally, Kodo 4 defaults to the dynamic schema factory, meaning it will not reflect on your schema to detect foreign keys (JDO's new relational mapping metadata allows you to specify foreign keys in your mapping, so Kodo 4 does not have to rely on schema reflection). If you continue to use Kodo 3 mappings and your schema has foreign key constraints Kodo must meet, set the following:

  • kodo.jdbc.SchemaFactory: native(ForeignKeys=true)

5.4.3. Configuration

Many confniguration properties and defaults have changed. Like previous Kodo releases, Kodo 4 will issue warnings if you attempt to set configuration options that it does not recognize. Refer to Chapter 2, Configuration for a complete listing of Kodo 4's configuration properties and defaults. Also, be sure to read Section 5.1, “Compatibility Configuration” above to learn about Kodo's special compatibility options.


Skip navigation bar   Back to Top