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.

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.

kodo2migrator *.jdo

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

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.

	Note
	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 kodo.properties file in your system CLASSPATH.

<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 -->
  <kodo2migrator>
    <fileset dir="${basedir}/src">
      <include name="**/*.jdo" />
    </fileset>
  </kodo2migrator>
</target>

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.

kodo2properties kodo.properties

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

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.

<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 -->
  <kodo2properties>
    <fileset dir="${basedir}/conf">
      <include name="**/kodo*.properties" />
    </fileset>
  </kodo2properties>
</target>

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.

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.