6.4. Migrating from Kodo 3.x to Kodo 4.0
Prev | Appendix 6. Upgrading Kodo | Next

## 6.4. Migrating from Kodo 3.x to Kodo 4.0

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.

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

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

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

| Note
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 `KODO_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)`

### 6.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 6.1, “Compatibility Configuration” above to learn about Kodo's special compatibility options.

Prev | Up | Next
6.3. Migrating from Kodo 3.1 to Kodo 3.2 | Home | Appendix 7. Development and Runtime Libraries