Q: How do I use GenerateMap?
Applies to: 1.x
GenerateMap is a sample application. It exists for two reasons. First, it shows you how to write code to use MapFactory_DTD. Second, you can use it as a tool to help you map a DTD to the database.
You are not required to use GenerateMap. That is, you can create your own tables and your own map document. The only reason to use GenerateMap is to make the process faster. That is, you can pass your DTD to GenerateMap and then modify the CREATE TABLE statements and map document to meet your own needs. In this way, GenerateMap will simply save you some typing.
When you pass a DTD to GenerateMap, it creates a table for each element with attributes, mixed content, or element content. It creates a column for each attribute and for each child element with PCDATA-only content. The names of the tables and columns are the same as the names of the elements and attributes. This can lead to name collisions, which GenerateMap does not (currently) try to resolve.
Because GenerateMap cannot tell which of your elements or attributes (if any) it can use as primary keys, it generates a primary key column for each table. If you want to use a specific element or attribute as a primary key, delete the XxxxxPK column from the CREATE TABLE statement and replace it with the appropriate column in the map document. (Similar changes apply to foreign keys.)
GenerateMap also assumes that you want to store order information in the database. Because of this, it creates XxxxxOrder columns. If order information is not important to you, remove these columns from the CREATE TABLE statements and remove the OrderColumn elements from the map document.
There are two other changes you might need to make. First, you will usually want to change the data types in the CREATE TABLE statement. (GenerateMap uses INTEGER for primary and foreign key columns and VARCHAR() for all other columns.) Second, if the database changes the case of names when it creates tables, you will need to change the case of the table and column names in the map to match the case of the names in the database.
In summary, use GenerateMap as a starting point, but feel free to change the tables and map document to transfer data in the way you want.
Note: The MapManager tool in version 2.0 solves many of the problems found in GenerateMap and also adds the ability to generate a map from a database schema. However, the generated maps must still be customized by hand.