This document describes how to migrate from Kodo 2 to Kodo 3. It assumes that you are using Kodo 2.4 or above. Unlike Kodo 2.x point releases, Kodo 3 is a major new release that introduces a lot of new functionality, but also changes many aspects of Kodo development. Kodo 3 absolutely will not work with Kodo 2 data unless you complete the steps below in the order that they appear.
![[Warning]](img/warning.gif) | Warning |
|---|---|
We strongly recommend that you back up all Java code, JDO metadata, and Kodo configuration files before proceeding. | |
The first and most difficult task in migrating to Kodo 3 is to compile all of your code against the Kodo 3 codebase. In addition to making Kodo more robust, flexible, and feature-packed, one of the primary goals of Kodo 3 was to clean up Kodo's APIs, making it easier for advanced users to understand and manipulate Kodo internals. Unfortunately, these API changes will break existing code that accesses Kodo-specific classes (as opposed to standard JDO interfaces). We cannot create a tool to automatically migrate your code for you, but we hope that our new Javadoc and this manual will make any necessary code changes as easy as possible. Our developer newsgroups and email support are also available for migration questions.
Kodo 3's package structure has been reworked to be shorter and more logical. The table below includes some of the more commonly-used Kodo 2 packages and their Kodo 3 equivalents.
Table D.1. Notable Package Changes
| Kodo 2 Package | Kodo 3 Package |
|---|---|
| com.solarmetric.kodo.runtime | kodo.runtime |
| com.solarmetric.kodo.conf | kodo.conf |
| com.solarmetric.kodo.query | kodo.query |
| com.solarmetric.kodo.meta | kodo.meta |
| com.solarmetric.kodo.runtime.datacache | kodo.datacache |
| com.solarmetric.kodo.runtime.datacache.plugins | kodo.datacache |
| com.solarmetric.kodo.runtime.datacache.query | kodo.datacache |
| com.solarmetric.kodo.runtime.event | kodo.event |
| com.solarmetric.kodo.runtime.event.impl | kodo.event |
| com.solarmetric.kodo.impl.jdbc | kodo.jdbc |
| com.solarmetric.kodo.impl.jdbc.ormapping | kodo.jdbc.meta |
| com.solarmetric.kodo.impl.jdbc.schema.dict | kodo.jdbc.sql |
In addition to package restructuring, many Kodo APIs have changed. The list below describes the differences in some of the more significant Kodo classes and APIs.
com.solarmetric.kodo.jdbc.JDBCConfiguration and com.solarmetric.kodo.jdbc.JDBCSimpleConfiguration have been replaced by kodo.jdbc.conf.JDBCConfiguration and kodo.jdbc.conf.JDBCConfigurationImpl , respectively. The Kodo 3 versions are very similar to the Kodo 2 ones, the only major difference being that Kodo 3 does not require a Connector argument to any methods, making it easier to access plugins.
com.solarmetric.kodo.impl.jdbc.JDBCPersistenceManagerFactory and com.solarmetric.kodo.impl.jdbc.ee.EEPersistenceManagerFactory have also been replaced. You may refer to one or both of these factories in your Kodo 2 application. In Kodo 3, you will only use the kodo.jdbc.runtime.JDBCPersistenceManagerFactory . Whether or not this factory dispenses managed persistence managers by default is controlled by the kodo.TransactionMode configuration property. The factory also has versions of the getPersistenceManager method that allow you to override the factory's default setting and retrieve managed or unmanaged persistence managers from the same factory instance as needed.
The com.solarmetric.kodo.impl.jdbc.schema.dict.DBDictionary has moved to kodo.jdbc.sql.DBDictionary, and its API has changed significantly. As before, we have included the source code to our dictionaries in your Kodo distribution. Note that Kodo 3 automatically avoids all naming conflicts when creating new tables, columns, and indexes by first reflecting on the existing schema to see what names are already in use. So if you were customizing a Kodo 2 dictionary just to avoid naming conflicts, you should be able to simply use a bundled dictionary in Kodo 3.
com.solarmetric.util.ObjectIds.Id has been replaced by kodo.util.Id.
Kodo's logging channels have been renamed to match the new package structure.
The Reference Guide demonstrates the new ways to access JDBC connections and use the sequence factory at runtime.
Kodo 3 has new Ant tasks for all included development tools. These tasks are described in Section 15.2, “Apache Ant”. As you change your build scripts, keep in mind that while Kodo 3 has something called the schema tool, it is very different than the Kodo 2 schema tool. For all intents and purposes, the Kodo 3 mapping tool replaces the Kodo 2 schema tool. You will probably never need to use Kodo 3's version of the schema tool directly.
Dependent objects are now deleted as soon as they are removed from their owning object. For example, if you have a Map field that you have annotated with the value-dependent metadata extension, calling Map.remove will cause the value associated with the removed key to transition to the persistent-deleted state immediately. See Section 6.2.1.2, “dependent” for details.
Additionally, in Kodo 3 we have added officially-supported interfaces for our API extensions to many of the core JDO classes. The following interfaces will be of particular interest: