3. Mapping Tool Basics
Contents
3.1. Introduction
3.2. The User Interface
3.1. Introduction
Whereas all previous discussions have used the term mapping strategy, the mapping tool interface and the remainder of this guide use the term schema or mapping schema in the same context. An application schema is the set of all mappings and other related information pertaining to a particular application. The mapping tool manipulates one application schema at a time just like a word processor manipulates one text file at a time (with the exception that the mapping tool can only keep one application schema open at any time).
An application schema is made up of the following types of schema objects:
| Schema Objects | |
|---|---|
| Object Name | Represents |
| Package | A Java Package in your application |
| Class | A persistent class in a Package |
| Attribute | A member variable in a Class |
| DB Configuration | A database configuration |
| Validity Check | An attribute validity check |
| SQL Command | A custom SQL statement or stored procedure |
| Heterogeneous Collection | A collection that holds objects of multiple classes |
An application schema is defined by creating all the necessary schema objects that represent an object model and mapping those schema objects to their RDBMS counterparts. Schema objects can be created manually using the Object->New menu option, or automatically from existing database tables or Java classes using either the Generate->Schema from database tables or Generate->Schema from Java classes menu options.
Application schemas can be saved in binary format with a file extension of .schema (e.g., contactdemo.schema) or in XML format with a file extension of .xml (e.g., contactdemo.xml). If an application schema file extension is changed to an unrecognized extension, the mapping tool will not be able to load it. Application schemas are saved by default in a repository directory named schrepository. This directory is created by default under the VBSF installation directory. The default repository directory may be moved to anywhere in your hard drive as long as its name is not changed and its parent directory is included in the CLASSPATH. You may also specify an alternate directory where application schema files are to be saved by using the vbsf.repository command line system property when the mapping tool is brought up. For details on the usage of this property, please refer to the Installation Instructions. It is strongly suggested that you maintain back ups of all your schema files.
If you cannot save or retrieve application schemas, and you are not using the vbsf.repository property, is because the schrepository directory is not located under a directory visible to the CLASSPATH.
The mappings for a single application may be defined using multiple application schemas, since VBSF has the ability to combine multiple schemas at runtime. This maybe useful for applications that map a large number of classes to the database, because it keeps the number of classes in each schema down to a manageable size. There are no restrictions on how a large application schema can be split up, as long as the mappings for each class are defined in their entirety within the same schema. For example, different classes in the same Java package maybe defined in multiple schemas, and subclasses may inherit from superclasses defined in other schemas.
3.2. The User Interface
The mapping tool interface is centered around a split pane whose left hand side displays a tree representation of the current application schema, and whose right hand side displays the information for the schema object currently selected in the tree. The split pane vertical separator bar may be moved to expand or contract either side of the pane.
When the root of the tree is selected the application schema options form is displayed in the right hand side of the split pane as shown above. This form contains the following fields:
Updateable. Check this option if the application schema can be modified at runtime. This is useful if a client application must change mappings.
Exposed. Check this option if clients can obtain mapping information at runtime.
Configuration file. This non-updateable field displays the name of the configuration file the application schema is using, or is blank if the schema uses the default configuration. See section 9. Working with Configurations for details.
Linked schema files. If an application's mappings are stored in multiple schema files, then you can use this field to specify all the schema files linked to the main one. This field should only be completed for the main schema file. The names of linked schema files are entered separated by commas and with no spaces in between. Entering this information allows you to specify just the name of the main schema file at runtime and VBSF will automatically load all linked schema files. Otherwise, you have to specify an array of schema names at runtime.
Schema Description. You can use this field to enter a long application schema description.
The Menu Bar
The menu bar contains the following options:
File
New Schema to create a new untitled application schema. Upon start up the mapping tool displays an empty untitled schema.
Open to open an existing application schema. This option displays the dialog box show below listing all existing application schemas.
Configuration to update, save, or load the current schema configuration. For more information see section 9. Working with Configurations.
Save to save the current application schema. If the schema is new and untitled you are prompted to enter the schema file name. Please note that if you exit the mapping tool without saving the schema ALL changes are lost.
Save As to save the current application schema under a new file name or extension. This option can be used to rename a schema, or to change its format from binary to XML, or vice-versa, by changing the extension.
Import to import a schema in text file format into the current schema. The current schema is completely overwritten.
Export to export the current application schema to a text file format. This option can be used for schema documentation purposes, or to edit the schema using a text editor (e.g., for mass changes to the schema using search and replace). The text file can be re-imported to binary format using the Import option.
Exit to exit the mapping tool.
Object
New to create a new schema object. The type of object created depends on which schema object or heading is selected in the tree when this option is invoked.
Delete to delete the schema object currently selected in the tree.
Rename to rename the currently selected schema object.
Copy to copy the currently selected schema object.
Move to move the currently selected schema object to another package or class.
Generate
Schema from Java classes to generate a default schema from existing Java classes. See section 11. Generating a Mapping Schema from Java Classes for details.
Schema from database tables to generate a default schema from existing database tables. See section 10. Generating a Mapping Schema from RDBMS Tables for details.
Source code from schema to generate Java source code from the current application schema. See section 12. Generating Source Code from a Mapping Schema for details.
DDL script from schema to generate a DDL script from the current application schema. See section 13. Generating a DDL Script from a Mapping Schema for details.
Compare schema with classes to compare compiled Java classes with the current application schema. This option is useful to compare Java classes with their corresponding schema in the event changes have been performed to either. See section 14. Comparing and Updating a Schema for details.
Update schema from classes to update the current schema from compiled Java classes. This option is useful to automatically synchronize Java classes with their corresponding schema in the event changes have been performed to either. See section 14. Comparing and Updating a Schema for details.
Database
Connect to connect to a database in order to generate a schema from existing tables and/or to obtain table and column look-up help in entry screens. See section below for details.
Disconnect to disconnect from the current database connection.
Help
About to display current version information.
3.3. Working with Schema Objects
Schema objects may be created, removed, renamed and copied using the Object menu options. The Insert and Delete keyboard keys may also be used as shortcut to the Object->New and Object->Delete menu options. All Object menu options are sensitive to the currently selected item in the tree.
The Object->New menu option can be invoked when the currently selected item in the tree is one of the following:
The remaining Object menu options can only be invoked when an actual schema object is selected in the tree (otherwise the command is ignored). The menu Object->Delete option also allows you to delete multiple schema objects of the same type at a time when multiple objects are selected on the tree. You will be prompted for confirmation before the actual deletion is performed as shown below:
If you want to generate a default mapping schema from existing database tables, or to be able to use table and column lookup help within the entry forms, you must connect to the database first. To connect to a database select the Database->Connect menu option. The following dialog box is then displayed so you can enter connection parameters:
You may enter default connection parameters that are saved to disk using the schema configuration options. The next time you connect to the database the connection dialog box will automatically display the connection parameters specified in the current configuration. For more information see section 9. Working with Configurations.
Before exiting the mapping tool you should close the database connection using the Database->Disconnect menu option. If you exit the application before explicitly closing an open connection you will be given the option (as shown below) to close the connection before returning to the operating system, or to cancel the exit operation.
