There are three primary approaches to object-relational mapping: object-to-schema, schema-to-object, and meet-in-the-middle. The mapping tool has actions to facilitate each approach.

In the object-to-schema approach to mapping, you concentrate your efforts on your object model, and the mapping tool's refresh action keeps your mappings and schema up-to-date. The refresh action examines both the existing database schema and any existing mapping information. Classes and fields that are not mapped, or whose mapping information no longer matches the object model or the schema, are automatically given new mappings. The tool also updates the schema as necessary to support these new mappings. The example below shows how to invoke the refresh action on the mapping tool to create or update the mapping information and database schema for the persistent classes listed in package.jdo.

mappingtool -a refresh package.jdo

You can safely run the refresh action on classes that have already been mapped, because the tool only generates new mappings when the old ones have become incompatible with the class or the schema. If the tool does have to replace a bad mapping, it does not modify other still-valid mappings. For example, if you change the type of a field from int to String, the mapping tool will detect the incompatibility with the old numeric column, add a new string-compatible column to the class' database table, and change the field's mapping data to point to the new column. All other fields will retain their original mappings.

To drop mapping data, use the drop action. This action does not affect the schema. Dropping mapping data for unused classes is not strictly necessary, but it might slightly increase performance under some mapping factories.

mappingtool -a drop package.jdo

The second approach to object-relational mapping is the schema-to-object approach. We have already seen how to use the reverse mapping tool to generate persistent classes and mapping information from an existing schema. Once you complete the reverse mapping, you may want to tweak the output of the reverse mapping tool. At this point you have both an existing schema and existing mapping information (from the reverse mapping tool), and you are modifying both by hand. Thus, you are really using the final, meet-in-the-middle approach to mapping.

In the meet-in-the-middle mapping approach, you control both the relational model and the object model. It is up to you to define the mappings between these models, possibly with the aid of Kodo JDO's GUI tools. In this scenario, you will find the mapping tool's validate action useful. The validate action verifies that the mapping information for a class matches the class definition and the existing schema.

mappingtool -a validate package.jdo

The buildSchema tool action is also useful for meet-in-the-middle mapping. Unlike the validate action, which throws an exception if the mapping data does not match the existing schema, or the refresh action, which replaces inconsistent mappings, the buildSchema action assumes your mapping data is correct, and modifies the schema to match your mappings. This lets you modify your mapping data manually, but saves you the hassle of using your database's tools to bring the schema up-to-date.

mappingtool -a buildSchema package.jdo

The buildSchema action is also useful if you would like Kodo to do most of your mappings, but you want to edit a few of the mappings or table/column names Kodo generates:

mappingtool -a refresh -sa none package.jdo

mappingtool -a buildSchema package.jdo

Finally, some mapping factories allow you to revert mapping data if they have saved a copy.

mappingtool -a revert package.jdo

Sometimes you do not want Kodo to make the changes to your database, but rather you want to have a script of the SQL that Kodo would use. In order to do this, you need to use mapping tool with schema tool (see Section 8.2, “Schema Tool”). This involves first writing the planned schema to an XML document (e.g. schema.xml) rather than modifying the data store. Then you need to ask the schema tool to create either the full DDL for the database, or just the DDL to bring the database up to date with your mappings. Note that this process can be automated using Ant (see Section 15.2, “Apache Ant”).

mappingtool -a refresh -sf schema.xml package.jdo
schematool -a build -f script.sql schema.xml

mappingtool -a refresh -sf schema.xml package.jdo
schematool -a add -f script.sql schema.xml

mappingtool -a buildSchema -sf schema.xml package.jdo
schematool -a build -f script.sql schema.xml

mappingtool -a buildSchema -sf schema.xml package.jdo
schematool -a add -f script.sql schema.xml

<target name="buildDDL">

    <!-- Define the mappingtool and schematool tasks; this can be    -->
    <!-- done at the top of the build.xml file, so it will be        -->
    <!-- available for all targets.                                  -->
    <taskdef name="mappingtool" classname="kodo.jdbc.ant.MappingToolTask"/>
    <taskdef name="schematool" classname="kodo.jdbc.ant.SchemaToolTask"/>

    <!-- Build a schema XML file for all .jdo files below the        -->
    <!-- current directory.  If we want to refresh the mappings at   -->
    <!-- the same time, we can use the "refresh" action instead.     -->
    <mappingtool action="buildSchema" schemaFile="${schemafile}">
        <fileset dir=".">
            <include name="**/*.jdo" />
        </fileset>
    </mappingtool>

    <!-- Build a DDL file that will add all the tables defined in    -->
    <!-- the schema file created above.  If we want the DDL to only  -->
    <!-- contain updates to the existing schema, we can use the      -->
    <!-- "add" action instead.                                       -->
    <schematool action="build" file="${ddlfile}">
        <fileset dir=".">
            <include name="${schemafile}" />
        </fileset>
    </schematool>
</target>