14. Comparing and Updating a Schema
The mapping tool provides compare and update options that can help you keep your Java classes and their corresponding schema in sync after changes have been made to either one. The compare option generates a report both on-screen and in a text file detailing any differences found. The update option automatically updates a schema from a set of Java classes by adding, removing, and renaming schema objects as necessary.
To utilize the compare option select the Generate->Compare schema with classes menu option to display the dialog box shown below.
The tool can only compare a schema against compiled Java classes (i.e. in byte code form). If the classes you are comparing the schema with belong to a Java package, you must enter, or select from the combo box drop down list, the package name that the classes belong to. If the classes do not belong to a package, you must enter the name of the directory where the classes reside. Once you specify either one, click the List Available Classes button to display the classes found in the Available list. If you specified a package name, the mapping tool will search for the directory where the classes reside using the system's CLASSPATH. If the directory is found the directory name will also be displayed in the Directory text field. If the directory is not found, make sure that the classes are located in a directory structure as expected by the class loader and under a parent directory specified in the system's CLASSPATH.
The Available list will show both abstract and concrete classes, but will exclude interfaces. Use the Add and Add All buttons to move classes from the Available list to the Selected list. You can also use the Remove and Remove All buttons to move classes from the Selected list back to the Available list.
Once the Selected list displays the classes that you want to compare against the current schema, click the Compare button to start the comparison process. When the comparison operation has completed a non-modal window listing all differences found is displayed as shown below:
All differences are reported in terms of what must be done to the schema in order to synchronize it with the Java classes. The report is also automatically saved as a text file named SchemaComparison.txt in the repository directory. Please note that the report might state that an attribute has to be added and another one removed, when in actuality the attribute was renamed. This can occur if multiple additions, deletions, or renames have occurred in the same class. In that case, the comparison operation cannot accurately determine whether an attribute was renamed, or whether it was deleted and another one added.
If the report is 100% (or mostly) accurate, and you want to update the schema with changes made to the Java classes, you can use the update function to automatically update the schema. If because of a large number of discrepancies the report is not accurate, you can still use the comparison report as a guideline and manually update the schema. To utilize the automatic update option select the Generate->Update schema from classes menu option, re-select the Java classes, and click the Update button to start the update process. The status bar at the bottom edge of the mapping tool will inform you when the update process has completed. The update process makes changes to the schema in memory. In order to make the changes permanent, use the use the File->Save menu option to save all changes to disk.
If instead of updating the schema, you want to update the Java classes with changes made to the schema, you can regenerate the sources for the affected classes. However, if you have implemented additional behavior, or added transient attributes to the affected classes, those changes will be overwritten so they must be re-applied after the sources are regenerated. The vposdemo2 sample application demonstrates a technique that can be used to handle this problem if you expect it to be an issue. To use this technique you define a base class that contains all persistent attributes, and a subclass that contains transient attributes and implements all behavior. The base class is the only one that is mapped to the database using the mapping tool. The subclass is also defined in the mapping tool, but no attributes are defined for it. The source code for the base class can then be regenerated as many times as necessary without overwriting any code that implements the behavior of the class.