9. Working with Configurations
Contents
9.1. Introduction
9.1. Introduction
The mapping tool allows you to store certain mapping tool defaults and preferences in a configuration file. These configuration settings are not used at runtime by the persistence layer. One configuration file may be shared by multiple application schemas. A configuration file may be saved in binary format with an extension of .config, or in XML format with an extension of .xml. Configuration files are stored in the same repository directory as the application schema files.
The default configuration file is named default and is automatically created the first time you save the default configuration to disk. You can also define multiple configurations saved under different file names if you wish. All new application schemas are assigned the default configuration by default. To display the configuration for the current application schema select the File->Configuration option from the menu which brings up the configuration dialog box. Once all editing of configuration settings is complete, the configuration must be saved or all changes will be lost.
You may save the configuration settings by clicking the Save button, or save the configuration settings under a new file name or in a different format (binary or XML) by clicking the Save As File button. The Save As File option automatically assigns the new configuration file to the current application schema, and saves the new configuration file in the repository directory.
You may also assign a different configuration to the current application schema by clicking the Load From File button. After selecting an existing configuration from the repository directory, the current application schema is assigned the replacement configuration and the contents of the configuration dialog box change to reflect the settings of the replacement configuration.
9.2. The Configuration Dialog Box
The configuration dialog box is divided into the following six tabbed panels:
Each tabbed panel is illustrated and explained in the following sections.
This panel allows you to specify settings related to source code and DDL script generation.
Source code generation settings:
Template file. Enter the name of the template file to be used. The full path name and file extension must be specified.
Output directory. Enter the directory where the source code files will be created. The full path name must be specified. The directory must exist prior to actual source code generation or a 'file not found' error will be displayed during source code generation.
Tab width. If the template file contains tabs, enter the number of spaces in a tab. If the generated source code does not seem to have proper left side indentations is because this setting is incorrect.
DDL script generation settings:
Template file. Enter the name of the template file to be used. The full path name and file extension must be specified.
Output file. Enter the name of the file to use for saving the DDL script. The full path name and file extension must be specified. If the file exists, it will be overwritten without warning.
Tab width. If the template file contains tabs, enter the number of spaces in a tab. If the generated DDL script does not seem to have proper left side indentations is because this setting is incorrect.
The small buttons on the right hand side of all file and directory name text fields can be used to pop up a file browser for selecting the file or directory.
This panel allows to specify default Java data types for each of the VBSF attribute types. The specified types are used as default when generating Java source code, reverse engineering a database, or manually creating new attributes. These types can be individually overridden in the Attribute Mapping Form if necessary. Recommended Java data types for simple attributes are listed in section 4.2.2. Simple Attributes. The types shown below are the default types.
To modify a Java type, double-click on its corresponding cell to enable cell editing mode. In order for the new cell value to be recorded you must either press the enter key, or exit cell editing mode by clicking or double-clicking on another cell. If you click the Save button while in cell editing mode, any changes made to the current cell will NOT be saved.
The Java Conversion Rules panel allows you to specify naming conversion rules to be followed when generating table and column names from Java class and attribute names. This setting is useful to automatically assign table and column names when generating a schema from Java classes. This setting is also used to automatically assign table and column names when class and attribute mappings are manually created using the Object->New menu option.
The following rules can be specified independently for table and column name conversions:
Do not generate. Inhibits any automatic generation of table or column names.
Maintain case. Each table or column has the same name as its class or attribute counterpart, preserving case.
First letter uppercase. A class or attribute name is converted to a table or column name by capitalizing the first letter and forcing all remaining letters to lowercase.
To all uppercase. A class or attribute name is converted to a table or column name by capitalizing all letters.
The DB Login panel is used to specify a default driver, URL, username and password for connecting to the database from within the mapping tool in order to obtain table and column look-up help, or to generate a schema from existing database tables. These settings do not apply at runtime. The Connection dialog box automatically displays these settings when connecting to the database, but allows you to overwrite them if necessary.
This panel allows to specify default database column data types for each of the VBSF attribute types. These types can be individually overridden in the Attribute Mapping Form if necessary. If you leave the column Data Type field in the Attribute Mapping form blank and generate a DDL script, the script generator will obtain default column data types from the values specified in this form. Column types are only used when generating a DDL script.
You can use the special notation *n* to denote a size marker. A size marker is dynamically substituted by the actual size specified in the Max Size field of the Attribute Mapping form during DDL script generation. This is very useful for string and floating point columns. Using a size marker is optional. You can instead specify the size in the column data type of each attribute. For example, you can define a 30 character string column by simply entering VARCHAR(30) in the Data Type field of the Attribute Mapping form, or by specifying VARCHAR(*n*) in the Data Type field and 30 in the Max Size field.
To modify a column type, double-click on its corresponding cell to enable cell editing mode. In order for the new cell value to be recorded you must either press the enter key, or exit cell editing mode by clicking or double-clicking on another cell. If you click the Save button while in cell editing mode, any changes made to the current cell will NOT be saved.
The column types shown below correspond to MS Access data types.
The DB Conversion Rules panel allows you to specify naming conversion rules to be followed when generating a schema from database tables.
The following rules can be specified:
Convert table names. Check this option if you want database table names to be converted to the standard Java class name format (i.e. first letter of each word capitalized and the remaining lowercase) when generating Class schema objects from database tables.
Convert column names. Check this option if you want that database column names be converted to Java attribute names using certain conversion rules. Checking this option enables the Column to Attribute Name Conversion panel which allows you to specify which conversion rules to follow when converting column names to attribute names.
Word Separator. If table and/or column names use a special word separator character or string, enter it here. Specifying a word separator allows the generator to identify words within table and column names so case conversion rules can be properly applied to each word in the table or column. For example, if a column is named LAST_NAME, you can enter the underscore (_) character as the word separator. If you specify the letter 'f" to be added as prefix, check the option to remove the separator, and you specify in the case conversion panels to force the first letter to uppercase and other all characters to lowercase, then the resulting attribute would be named: fLastName.
Remove separator. Check this option if you have specified a word separator, and you want the word separator removed from the resulting class and attribute names.
Case Conversion Panel
Maintain case. Inhibits any column to attribute case conversion.
To all lowercase. Forces the attribute name to be lowercase.
To all uppercase. Forces the attribute name to be uppercase.
First Letter Case Panel (case conversion rules that apply only to the first letter of the attribute)
As in case conversion. Uses the rules specified in the Case Conversion Panel.
Force to lowercase. Forces the first letter of the attribute name to be lowercase.
Force to uppercase. Forces the first letter of the attribute name to be uppercase.
Add Prefix. Enter an optional prefix to add to the attribute name.
Add Suffix. Enter an optional suffix to add to the attribute name.
Remove substring. Enter an optional string to be removed from the column name.
The DB Generation Options panel allows you to specify whether REFERENCE and REFERENCED COLLECTION attributes should be automatically created when generating a schema from database tables. (See section 10. Generating a Mapping Schema from RDBMS Tables for details.) The mapping tool can infer class relationships by looking at the foreign key and references constraints defined in the database, and automatically generate REFERENCE and REFERENCED COLLECTION attributes. In order for this to work, such constraints must be defined in the database and the driver must be capable of providing this information. The JDBC/ODBC bridge, for example, is not capable, but most commercial quality JDBC drivers (such as those by WebLogic) are able to.
The following options can be specified:
References Panel
Generate REFERENCE attributes. Check this option if you want to automatically generate REFERENCE attributes for your persistent classes. The column to attribute name conversion rules specified in the previous panel, if any, are automatically applied when generating REFERENCE attributes.
Remove ID descriptor from name. Check this option to automatically remove an ID descriptor when converting the column name to the attribute name.
For example, consider an Invoice object that maintains a reference to a Customer object by means of a REFERENCE attribute named fCustomer, and assume that in the Invoice table the foreign key column pointing to the primary key of the Customer table is named CustomerID. In this case we want to convert the column name CustomerID to an attribute named fCustomer. To do this we must first specify in the Conversion Rules panel the attribute name conversion rules as follows:
| Conversion Rules Panel Settings | |
|---|---|
| Field | Setting |
| Convert column names | Checked |
| Maintain case | Selected |
| As In Case Conversion | Selected |
| Add prefix | f |
Then we check the Remove ID descriptor from name option and specify ID as the ID descriptor string to be removed from the column name in the ID Descriptor text field.
Collections Panel
Generate REFERENCE COLLECTION attributes. Check this option if you want to automatically generate REFERENCE COLLECTION attributes for your persistent classes. When REFERENCE COLLECTION attributes are generated there is no corresponding column name in the table, therefore the referenced table is taken as the starting attribute name. Most likely the table name will not be suitable as an attribute name so the options below can be used to convert the table name to a more suitable attribute name.
Apply attribute conversion rules. Check this option to apply the attribute name conversion rules specified in the previous panel to the REFERENCE COLLECTION attribute names.
Convert name to plural. Check this option to automatically convert the REFERENCE COLLECTION attribute name to plural.
Convert ending 's' to 'ses'. Check this option to automatically convert attribute names ending in 's' to 'ses' when changing the attribute name to plural.
For example, consider a LineItem table with a foreign key column named InvoiceID pointing the primary key of an Invoice table. In this case we want to generate a REFERENCE COLLECTION attribute in the Invoice class to access its LineItem objects. If we check the Generate REFERENCE COLLECTION attributes option, but do not specify any of the other options, the REFERENCE COLLECTION attribute will be named LineItem (i.e. the name of the table being referenced). In order to convert this attribute name to a more suitable name of fLineItems we would also need to check the Apply attribute conversion rules and Convert name to plural options.