Appendix D. Upgrading Kodo

D.1. Migrating from Kodo 2 to Kodo 3
D.1.1. Source Code Migration
D.1.1.1. Package Structure Changes
D.1.1.2. API Changes
D.1.2. JDO Metadata Migration
D.1.3. Properties File Migration
D.1.4. Storing Object-Relational Mapping Data
D.1.5. Kodo 3 Development Process
D.2. Migrating from Kodo 3.0 to Kodo 3.1
D.3. Migrating from Kodo 3.1 to Kodo 3.2

This document describes how to upgrade to a new version of Kodo from the prior version. When skipping versions, please follow the steps outlined as though you are converting to each intermediate version.

D.1. Migrating from Kodo 2 to Kodo 3

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.


We strongly recommend that you back up all Java code, JDO metadata, and Kodo configuration files before proceeding.

D.1.1. Source Code Migration

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.

D.1.1.1. Package Structure Changes

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 PackageKodo 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

D.1.1.2. API Changes

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 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, “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:

D.1.2. JDO Metadata Migration

The next step in switching to Kodo 3 is to migrate your JDO metadata. This is necessary for two reasons. First, Kodo 3 changes many metadata extension keys to differentiate between back-end independent extensions and jdbc-specific extensions. Second, and more importantly, Kodo 3 changes the way object/relational mapping data is stored.

In Kodo 2, object/relational mapping data was read from JDO metadata extensions. If no mapping extensions existed, then the system assumed that you wanted to use the "default" mapping, and dynamically created one at runtime. While this process was convenient, it was not very robust, because no validation of mappings against the schema was performed, and there was no record of mappings to consult for conflict avoidance. Furthermore, Kodo could never improve on its mapping defaults because anyone who relied on them would be left with an invalid schema.

Kodo 3 remedies these problems by always recording all mapping data, rather than relying on unspecified defaults. This leads to better validation, fewer conflicts, and more robust handling of Java class changes. As with Kodo 2, you can write mapping data yourself, or rely on the system to do it for you. As you will see, we offer several choices of where to record mapping information, from JDO metadata extensions to XML mapping files to storing it in a special database table.

The Kodo 2 migrator tool can automatically migrate all of your JDO metadata. You can invoke the tool via the included kodo2migrator script or via its Java class, kodo.jdbc.migration.kodo2.Kodo2Migrator. The tool also comes with an Ant task, which we present later in this section.

Example D.1. Using the Kodo 2 Migrator

kodo2migrator *.jdo

The migrator accepts the standard set of command-line arguments defined by the configuration framework , along with the following flags:

  • -file/-f <stdout | output file or resource> : The path or resource name of a file in which to store the mapping information linking your existing persistent classes to your schema. By default, the migrator creates mapping files that mirror the structure of your JDO metadata files.

Each additional argument to the tool should be the class name, .class file, .java file, or .jdo file of a persistent type. The type must be compiled. The existing metadata file for the type will be backed up to <file-name>~, and a new JDO metadata file will be generated in its place. Object-relational mapping data will be calculated and written to separate .mapping files mirroring the structure of your .jdo files, or to the file you specified in the -file command-line argument.

You should run the Kodo 2 migrator tool on all of your persistent classes at once. One easy way to do this is through the tool's Ant task, kodo.jdbc.ant.Kodo2MigratorTask. The attributes of the task correspond exactly to the long versions of the command-line arguments accepted by the tool. Additionally, see the chapter on Ant integration for common configuration options available to all Kodo tasks.


The Kodo 2 migration task has dependencies on both old and new Kodo code, and therefore is very sensitive to the invocation environment. The easiest way to ensure the correct environment is to include your classes and the directory containing your Kodo 2.x file in your system CLASSPATH.

Example D.2. Invoking the Kodo 2 Migrator from Ant

<target name="migrate-meta">
  <!-- define the kodo2migrator task; this can be done at the top of -->
  <!-- the build.xml file, so it will be available for all targets   -->
  <taskdef name="kodo2migrator" classname="kodo.jdbc.ant.Kodo2MigratorTask"/>

  <!-- invoke migrator on all .jdo files below the src directory -->
    <fileset dir="${basedir}/src">
      <include name="**/*.jdo" />

D.1.3. Properties File Migration

After migrating your JDO metadata, you can migrate your Kodo configuration properties files. You must do this after migrating your JDO metadata so that the migrator tool can draw on your Kodo 2 mapping preferences.

The Kodo 2 properties tool can automatically migrate your configuration files. You can invoke the tool via the included kodo2properties script or via its Java class, kodo.jdbc.kodo2.Kodo2Properties. The tool also comes with an Ant task, which we present later in this section.

Example D.3. Using the Kodo 2 Properties Tool


The tool accepts the standard set of command-line arguments defined by the configuration framework , along with the following flags:

  • -file/-f <stdout | output file or resource> : The path or resource name of the migrated properties file. You should only use this argument if you want to override the default behavior of overwriting the original file (after backing it up), and only if you are invoking the tool on only a single properties file.

Each additional argument to the tool should be a Kodo 2 properties file. Unless a -file argument is given, the file will be backed up to <file-name>~, and a new properties file will be generated in its place.

The Kodo 2 properties tool can also be invoked via its Ant task, kodo.jdbc.ant.Kodo2PropertiesTask. The attributes of the task correspond exactly to the long versions of the command-line argument accepted by the tool. Additionally, see the chapter on Ant integration for common configuration options available to all Kodo tasks.

Example D.4. Invoking the Kodo 2 Properties Tool from Ant

<target name="migrate-props">
  <!-- define the kodo2properties task; this can be done at the top of -->
  <!-- the build.xml file, so it will be available for all targets     -->
  <taskdef name="kodo2properties" classname="kodo.jdbc.ant.Kodo2PropertiesTask"/>

  <!-- invoke tool on all the conf/kodo*.properties files -->
    <fileset dir="${basedir}/conf">
      <include name="**/kodo*.properties" />

D.1.4. Storing Object-Relational Mapping Data

Please read the reference guide's description of the available mapping factories in Section 7.3, “Mapping Factory”. If you are satisfied with the default of storing mapping data in .mapping files, then there is nothing to do. If you'd like to switch to another mapping data format, however, the above chapter describes your options and shows you how to migrate your mapping data between factories.

You are now ready to develop with Kodo 3.

D.1.5. Kodo 3 Development Process

The development process under Kodo 3 is slightly different than it was under Kodo 2. For example, the familiar schematool has been replaced with the more powerful mappingtool. You should take a moment to read through the revised Kodo tutorials and the Reference Guide to familiarize yourself with the new processes under Kodo 3 and the new features available to you.

Also, be sure to read the release notes for all Kodo 3 releases, including the betas. The Notable Changes section of each note lists topics you should be aware of in your migration.