3.3. Generating Persistent Classes

First, make sure that you are in the
reversetutorial directory and that you've
made the appropriate modifications to your
kodo.properties file, as described in the
previous section.

Now that we have our environment set up correctly, we're
going to dump our existing schema to an XML document. This
step is not strictly necessary for Hypersonic SQL, which
provides good database metadata. Some databases, however,
have faulty JDBC drivers, and Kodo JDO is unable to gather
enough information about the existing schema to create a
good object model from it. In these cases, it is useful to
dump the schema to XML, then modify the XML by hand to
correct any errors introduced by the JDBC driver. If your
schema doesn't use foreign key constraints, you may also
want to add logical foreign keys to the XML file so that
Kodo JDO can create the corresponding relations between the
persistent classes it generates.

To perform the schema-to-XML conversion, we're going to use the
schema generator, which can be invoked via the
included schemagen shell script.
The -file flag tells the
generator what to name the XML file it creates:

Examine the schema.xml XML file created
by the schema generator. As you can see, it contains a complete
representation of the schema for your magazine database. For
the curious, this XML format is documented in
Section 8.3, “XML Schema Format” of the Reference Guide.

Run the reverse mapping tool on the schema file.
(If you do not supply the schema file to reverse map, the tool
will run directly against the schema in the database). The
tool can be run via the included
reversemappingtool script. Use the
-package flag to
control the package name of the generated classes.

The .mapping file generated by the reverse
mapping tool is suitable for use with the default
file mapping factory
. Kodo JDO offers other factories that store mapping
data in other formats.

As shop owner, you've decided that you don't want an extra
.mapping file lying around like you have
now. Instead, you'd like to store the mapping information in
the JDO metadata file, using metadata's built-in extension
mechanism. Kodo JDO supports storing object-relational mappings
in JDO metadata with the
metadata mapping
factory. To use this factory, add the following line
to the kodo.properties file:

kodo.jdbc.MappingFactory: metadata

Whenever you switch mapping factories, you have to
import the .mapping file data into the
new factory. We accomplish this with the
mapping tool
. Make sure to compile the generated classes before
the import:

javac *.java
mappingtool -action import package.mapping

You can now delete the mapping file if desired.

Examine the generated persistent classes. Notice that the
reverse mapping tool has used column and foreign key data to
create the appropriate persistent fields and relations between
classes. Notice, too, that due to the transparency of JDO, the
generated code is vanilla Java, with no trace of JDO-specific
functionality.

Also examine the generated application identity classes. Note
that they satisfy all of the requirements for application
identity classes mandated by the JDO specification, including
the equals and hashCode
contracts.

Finally, examine the package.jdo
metadata file. It contains the necessary standard JDO metadata,
plus, thanks to our use of the mapping tool's import action,
the necessary Kodo JDO extensions to map the classes and
their fields to the existing schema.

The reverse mapping tool has now created a complete JDO object model for
your magazine shop's existing relational model. From now on, you can
treat the generated JDO classes just like any other JDO class. And that
means you have to complete one additional step before you can use the
classes with persistence: enhancement.

jdoc package.jdo

This step runs the Kodo JDO enhancer on the
package.jdo file mentioned above. The
package.jdo file contains an enumeration of
all the classes that should be JDO enhanced. The Kodo JDO enhancer will
examine the file's metadata and enhance all listed classes
appropriately. See Section 5.5, “Enhancement” in the
Reference Guide for more information on the JDO enhancer.

Congratulations! You are now ready to use JDO to access your magazine
data.