Chapter 3. Generating Persitent Classes
Prev | Part V. Reverse Mapping Tool Tutorial | Next

## Chapter 3. Generating Persitent 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.

| Note
Because reverse schema mapping comes from Solarmetric's R&D codebase, the tool scripts all have the `rd-` prefix. The R&D codebase also uses the same Apache commons logging framework used in Kodo JDO 2.4 beta and above. See the commons logging API if you need to configure logging.

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

2. Now that we've got 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 can be invoked via the included `rd-schemagen` shell script, or through its Java class, `com.solarmetric.rd.kodo.impl.jdbc.schema.SchemaGenerator` . The `-file` flag tells the generator what to name the XML file it creates:

       rd-schemagen -file schema.xml
       or
       java com.solarmetric.rd.kodo.impl.jdbc.schema.SchemaGenerator -file schema.xml

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.

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 `rd-reversemappingtool` script, or through its Java class, `com.solarmetric.rd.kodo.impl.jdbc.meta.ReverseMappingTool` . Use the `-package` flag to control the package of the generated classes.

       rd-reversemappingtool -package reversetutorial schema.xml
       or
       java com.solarmetric.rd.kodo.impl.jdbc.meta.ReverseMappingTool -package reversetutorial schema.xml

   Running the tool will generate `.java` files for each generated class, `.java` files for corresponding JDO application identity classes, a `reversemapping.jdo` JDO metadata file, a `reversetutorial.schema` file, and a `reversetutorial.mapping` file. The schema file is there to show you what portion of the schema was mapped; it serves no other purpose and can be deleted if desired. The mapping file contains the O/R information mapping the generated classes to your existing schema. Mapping files like these will be offered as an optional alternative to Kodo JDO's standard JDO metadata extensions in a future version of Kodo JDO. For now, you must import the mapping information into Kodo JDO metadata extensions.

5. To import the generated O/R mapping information into metadata extensions, run the R&D import tool on the mapping file. The tool can be invoked via the included `rd-importtool` script or through its Java class, `com.solarmetric.rd.kodo.impl.jdbc.meta.compat.ImportTool` . Make sure to compile the generated classes before the import:

       javac *.java
       rd-importtool reversetutorial.mapping
       or
       java com.solarmetric.rd.kodo.impl.jdbc.meta.compat.ImportTool reversetutorial.mapping

   You can now delete the mapping file if desired.

6. 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 `reversetutorial.jdo` metadata file. It contains the necessary standard JDO metadata, plus 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 two additional steps before you can use the classes with persistence.

- Enhance the JDO classes.

      jdoc reversetutorial.jdo
      or
      java com.solarmetric.kodo.enhance.JDOEnhancer reversetutorial.jdo

  This step runs the Kodo JDO enhancer on the `reversetutorial.jdo` file mentioned above. The `reversetutorial.jdo` file contains an enumeration of all the classes that should be JDO enhanced. The Kodo JDO enhancer will examine the contents of this file and enhance all classes listed in it according to the metadata defined in the file. See the enhancer section of the Reference Guide for more information on the JDO enhancer.

- Register the persistent classes. If you are using Kodo JDO version 2.3.x or below, you need to register all persistent classes with Kodo JDO. The easiest way to do this is with the schema tool:

      schematool -action register reversetutorial.jdo
      or
      java com.solarmetric.kodo.impl.jdbc.schema.SchemaTool -action register reversetutorial.jdo

  The schema tool creates a special table in the database to hold the names of registered classes.

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

Prev | Up | Next
2.2. Important Utilities | Home | Chapter 4. Using the Finder