3.3. Generating Persistent Classes

Now it's time to turn your magazine database into persistent JDO classes mapped to each existing table. To accomplish this, we'll use Kodo JDO's reverse schema mapping tools.

  1. 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.

  2. 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:

    schemagen -file schema.xml
    

    The schema generator is described in detail in Section 8.1.3, “Schema Generator” of the Reference Guide.

  3. 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.

  4. 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.

    reversemappingtool -package reversetutorial schema.xml
    

    The reverse mapping tool has many options and customization hooks. For a complete treatment of the tool, see Section 5.6, “Auto-Generating Classes from a Schema” of the Reference Guide.

    Running the reverse mapping tool will generate .java files for each generated class, .java files for corresponding JDO application identity classes, a reversemapping.jdo JDO metadata file, and a package.mapping file. The mapping file contains the object-relational information linking the generated classes to your existing schema. Section 7.4, “Mapping File XML Format” of the Reference Guide discusses the mapping file format in detail.

  5. 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
    
  6. 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.

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