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