4.8. Visualize Mapping

Kodo Workbench will generate a visual representation of the mapping information that Kodo will use to persist data at runtime. Each class and table for the selected mappings will be laid out as nodes of a graph on the canvas. Each class is represented in blue with the mapping icon beside the class name. Each table is in green with the table icon beside the table name. Tables found also in the Workbench schema will also be annotated with its columns' types.

You can edit the mapping information for each selection. By selecting a class, for instance, you can choose a different table to store the data columns. When you select a class or field, you will see detailed information presented in the Details pane. The Details pane will show all the current mapping information for the current selected item. In addition, you will see a selection of colored buttons which you can use to map the current selection.The currently selected option will be highlighted with a yellow border.

You can now select in the detail pane the colored buttons to link the mapping to the proper schema object. For example, by selecting a class, one may see buttons for table and primary key column. By selecting table, one can see that there is now a dashed temporary line leading from the class to the cursor. You can now move the line and "drop" it to select a new table for the class. Similarly, one can similarly select a column name for column attributes. The final type of link attribute are most often found in foreign key mappings. In these links, Kodo Workbench will prompt you for a source column which is being linked to the selected target column. You can see the results in the attribute table and also in the corresponding editor.

You can use foreign keys in a similar fashion to the way you set column and table values for your mappings. In this situation, when dealing with ref-column attributes, the visualization editor will populate the table and reference column attributes. When selecting a foreign key for data columns, it will populdate the column information that is appropriate for the type of attribute (i.e. data-column, element-column, etc).

You can tailor the amount of information shown on the graph. By right clicking anywhere on the graph and selecting Edit Detail, a dialog offering different visualization toggles will appear. Select what portions of the graph you want the system to generate. You can also view a legend of line colors and their meanings by right clicking on the graph and selecting View Legend. Each node is draggable by the mouse (click and drag) so that you can re-arrange the layout as you see fit.

Finally, using the right click menu, you can import the Workbench schema to use in your mapping. Select Add/import Tables, and then choose to import the entire schema or a subset of schemas/tables. This allows you a quick way to map your classes to your existing schema.

By using the keyboard and putting the scrolling canvas in focus, you can scale and zoom the graph by using the +/= key to zoom in and the -/_ key to zoom out. Press the space bar to return the canvas to normal zoom.

In addition to the table and class nodes, you may also see yellow mapping nodes. For foreign key-based field mappings, Kodo Workbench will generate this node indicating the type of mapping used for the linked field. These nodes are linked back to the owning field by a green line.

There are a number of other lines in the system which each represent a different part of the Kodo mapping system.

Table 4.1. Graph Edges

Line ColorDefinition
- Dark Blue Class Inheritance
- Dark Green Class Mapping
- Black Datastore Primary Key Column
- Light Green Field Mapping
- Light Blue Data Column
- Purple Key Column
- Red Reference Target
- Magenta Persistent related field type
- Yellow Element persistent type
- Dark Purple Key persistent type

You can close the visualization component by closing it like any other editor (File -> Close). The visualization component will also ask you if you want the graph regenerated after one of the visualized class mappings have changed.