Import from Database Generator

The following table of contents provides an outline of the documentation for this generator.

• 1. Overview
  • 1.1 Generator inputs
  • 1.2 Generator outputs
• 2. Configuration
  • 2.1 Generator parameters
  • 2.2 Model configuration
  • 2.3 Common configurations
• 3. How to use the generator
  • 3.1 Running the generator
  • 3.2 Customizing the output
  • 3.3 Cleaning generator’s output

1. Overview

This generator helps you jump-start Xomega object modeling by importing the model from an existing SQL Server database. The generator builds the objects and fields from the corresponding database tables and columns, declares logical types and fieldsets for object keys so that to preserve relationships between objects, and declares reusable types for all other object fields.

Prior to running the generator though, you need to make sure you pre-configure the model as described below.

1.1 Generator inputs

The generator takes the structure of the target database, and creates model types, fieldsets and objects for the database tables, except for any tables that were excluded from the import.

Logical Types. The generator will try to map the database types to one of the existing Xomega types or, if not possible, will define a new type that derives from one of the existing types. Therefore, before you run the import you may want to make sure the existing types' configuration is consistent with your current system standards. For example, the boolean type maps by default to a SQL Server type bit, as shown below. However if the standard for your current system is tinyint to store a boolean, then you should update the Xomega type to map to tinyint, so that it can be properly identified by the generator.

Field-sets. By the same token, the generator can identify groups of fields that match one of the field-sets defined in the model and use a reference to the field-set instead of those fields. If all or most of your tables, for example, have a set of standard audit columns, such as the user who created the record and the creation time stamp, then you can just define such a fieldset in your model first and it will be automatically used by the imported objects. If later on you will want to also add the user who last modified the record and the last modification time stamp, then you could just add them to that field-set definition and they will be automatically included in all the objects that use that field-set.

Foreign Keys for Subobjects. What you should also be cognizant of is that Xomega subobjects are inseparable from their parent objects and require a cascading deletion whenever their parent object is deleted. As a result, for the Import generator to define objects as subobjects, their foreign key relationship to the parent object should have cascading deletion and the columns on both ends of the relationship should have the same names. If you would like some tables to be imported as child objects then you may want to consider updating their foreign key relationship accordingly before the import.

You can obviously refactor the model structure after you import it, but sometimes it may be easier to make some changes in the model or the database initially, delete the generated objects, and re-import them again.

1.2 Generator outputs

This generator creates a single or multiple .xom files with objects, fieldsets and logical types as defined by the OutputPath parameter, and adds them to the model project.

Logical Types. For the columns where the generator cannot map the database type to one of the existing Xomega types, it will define a new type that derives from one of the existing types, and will use it on all columns with the same type, as illustrated below. You can rename and refactor such types after the import to give them proper logical names, e.g. "phone number".

Key Types. For primary keys the generator will define either a simple logical type, or a fieldset, if the key is composite with more than just parent table's key. The following snippet illustrates this setup. For sub-objects, the primary key of the parent object will be dropped from the list of fields, as it is included implicitly.

Fixed Table Names. If you set the Keep Table Names parameter of the generator to "true", the generated objects will have a configuration element with a sql:table element that provides a mapping to the DB table name, as follows. This allows renaming generated objects without worring about affecting the table name. Without such a configuration, the table name for the object will be implicitly derived from the object's full name using specified database naming conventions (case).

Fixed Column Names. If you set the Keep Column Names parameter of the generator to "true", the fields on generated objects will have a configuration element with a sql:column element that provides a mapping to the DB column name, as follows. This allows renaming generated objects' fields without worring about affecting the column name. Without such a configuration, the column name for the field will be implicitly derived from the field's name using specified database naming conventions (case).

2. Configuration

The following sections describe configuration parameters used by the generator.

2.1 Generator parameters

The following table lists configuration parameters that are set as the generator’s properties.

Parameter	Value Example	Description
Generator Name	Import from Database	The name of the current configuration of the generator that will appear in the model project and the build output.
Folder Name	Model Enhancement	Folder path to the generator inside the Model project. The folders are separated by a backslash (\).
Include In Build	False	A flag indicating whether or not running this generator should be included in building of the model project.
Output
Output Path	Import/{Module/}{File}.xom	Relative path where to output generated .xom files, which will be added to the model project. The path may contain {Module/} and {File} placeholders to output files by database schema and table respectively.
Database
Database	SQL Server	Database type of the source database. Currently only SQL Server (sqlsrv) is supported. Value 'Use Project Settings' takes this value from the corresponding property of the model project.
Database Version	11.0	The version of the source database. Value 'Use Project Settings' takes this value from the corresponding property of the model project.
Database Case	CamelCase	The database case for the database objects' names: UPPER_CASE, lower_case or CamelCase. Value 'Use Project Settings' takes this value from the corresponding property of the model project.
Database Connection	Use Project Settings	Database connection string for the source database. Edited via a 'Database Connection Configuration' dialog, which also sets the other Database parameters of the generator, and saving all this configuration for the entire project. Value 'Use Project Settings' takes this value from the corresponding property of the model project.
Naming Convention
Keep Table Names	True	Whether or not to preserve table names in generated objects.
Keep Column Names	True	Whether or not to preserve column names in generated objects.
Keep Constraint Names	False	Whether or not to preserve constraint names in generated objects.
Naming Case	lower	The case to use for logical names: lower, upper or camel. Leave empty to use DB names as is.
Naming Delimiter	space	The delimiter to use for logical names: space, underscore or dash. Leave empty to use DB names as is.

2.2 Model configuration

The generator doesn't use any other configuration parameters from the model.

2.3 Common configurations

When importing the model from a database you should first of all define the database connection for the generator. You can do it via the Database Connection Configuration dialog that pops up from the generator's Properties page. In that dialog you should specify an OLE DB connection string to your database, which Xomega will validate and use to read your database metadata. On the next tab of the dialog you can specify which database tables you would like to exclude from the model. Next, the system will try to determine if your database names are case-sensitive and will set the Database Case to CamelCase or your choice of UPPER_CASE or lower_case respectively, which will be used for generating tables for all new objects as well.

It makes sense to save this database configuration as default project settings, which will be one of the options in the dialog, so that all other database-related generators could reuse the same settings. This way, for example, the database change script generator won't try to remove the tables that have been explicitly excluded from the model. If you save it as a default configuration then it will be available in the model project's Properties page, and the corresponding generator properties will be set to the 'Use Project Setting' value.

3. How to use the generator

The sections below provide some details on how to work with the generator.

3.1 Running the generator

You can run this generator for the entire database or for a subset of tables after configuring the database generator parameters. The model must contain no objects defined when the generator runs to prevent overwriting any custom changes if you rerun it. The generated Xomega files will be automatically added to the project under the folder designated by the Output Path property. You can make it output to the project folder, but initially you may want to consider generating it in some project sub-folder (such as the default Import/ folder). This will allow you to review the generated files, and clean them all easily if you realize that you need to make any adjustments in the database or the configuration, and then rerun the generator.

3.2 Customizing the output

If upon review of the imported model you would like to re-import it differently, you will need to remove all of the generated objects, make the necessary changes in the generator parameters, such as whether or not to keep table or column names, or in the model, such as defining new types or fieldsets that can be used by the import, or in the database, such as adding foreign keys with cascade delete between parent objects and sub-objects, and then rerun the generator.

After that you can make any necessary changes directly in the model without rerunning the generator anymore.

3.3 Cleaning generator’s output

This generator does not support cleaning of the generated files. While you review the initial import of the model from the database, you may want to output the imported objects into a dedicated folder under the model project, so that it would be easy to delete the generated folder, make the necessary updates, and rerun the generator.