## NewGen Package

NewGen package is used for source code generation based on UML class model and parametrized by generator template. Generally it follows the MDA (Model-Driven Architecture) specification while extends it with optional object-to-database mapping functionality. Package contains the next modules -

1. Template Editor. Optional module. Is used to create and edit generator templates. Any text editor can be used instead of Template Editor.
2. Template Compilator. Compiles templates into GEN file used for source code generation. Templates must follow MacGen Syntax requirements.
3. Map Tool. Optional module used to extend UML model with database mapping information. Usefull in case of generation of persistent classes with hardcoded database mapping. Includes generator functionality.
4. Debugger. Source code generator with debugging functionality. Generates code based on class model structure stored in XML file (XMI standard) and generator template information from the GEN file.
5. Generator. Source code generator itself. Generates code based on class model structure stored in XML file (XMI standard) and generator template information from the GEN file. Generator has been implemented based on NewGen engine.

Structure of NewGen Package with processing dependability -

- Template Editor (MacroEdit.exe); creates

- Template

- Template Compilator(Comp.exe or NewGen.exe), uses

- Template file

- MapTool (MapTool.exe), uses

- Mapping repository
- XMI file
- Oracle and/or ODBC database
- Compiled template (GEN file)

- Debugger and Generator(Gen.exe or NewGen.exe), use

- NewGen Engine, uses

- Compiled template (GEN file)

- GenProcessor, uses

- Mapping repository
- XMI file

Picture1. MGL package modules.
Command-line programms

- Comp.exe - compiles templates into single GEN file used by generator.
- Gen.exe - generates output text based on class model (XMI parameter), mapping information (REPO parameter) and compiled generator template (GEN parameter). You also have to specify path to class or package in XMI hierarchy you want generate text for and optionally output file. XMI, REPO, GEN and OBJ parameters can be ommited if you have project file (MAP parameter).

GUI programms

- MacroEdit.exe - simple editor for macro (template) files.
- MapTool.exe - combines mapping repository editor and generator; works with project files.
- NewGen.exe - interactive tool to show generator tree, link templates and generate output file with debugger.

Also you need to have any UML tool with capability to export class structure into XML file (XMI specification, versions 1.0 and 1.1 are supported). Enterprise Architect and Rational Rose were used for package testing.
Class/DB mapping extention of UML
UML model includes information about class structures and associations between classes. Also it has possibility to depict structutre of underling database. But there are no standard UML specification to map class structure to database structure. You always have possibility to extend UML model by tag values but it is not convinient way for class/DB mapping until it is supported by UML tool. As result XMI file contains no information about mapping. MapTool allows you to extend information from XMI. It uses additional file for mapping data and doesn't override original XMI file. After that, you can generate source files based on UML model and your mapping information. It is not neccessary to map your classes if they don't store their state in database tables.
Generation process

1. Template creation
   Use Template Editor (MacroEdit.exe) or any other text editor to create and edit your templates. As start point you can get sample templates and modify them to fit your requirements.You can generate any kind of text file based on your model information. Macro generator used with NewGen package produces output file based on literal text, macro commands, variables and macro constants. See MacGen Syntax.
2. GEN file compilation
   Use Template Compilator (Comp.exe or NewGen.exe) to compile you templates into GEN file.
3. Class model defenition
   Define your class model. You can use Rasional Rose(tm), Enterprise Architect(tm) or any other UML tool wich can generate XML file following the XMI convention.
   MapTool hase some assumptions about your UML model structure (see UML requirements). After model definition work is done you export your model as XML file.
4. Creation of MAP file.
   MAP file contains all configuration parameters required for mapping and generation. In MapTool create new project (*.map file), in properties form (Ctrl-P) set class definition (your XML file), Oracle and ODBC connection (if you need to provide mapping information), and select desirable template for generation.
5. Mapping
   Each class in your model can be mapped to particular table or view in the underlying database (or databases). Each attribute in your class can be mapped to the table or view column. MapTool supports only plain class-to-table mapping. If you need to map your class to several tables, you need to create a view wich will join these tables.
6. Generation
   Run generator(Gen.exe or NewGen.exe). Two parameters are required - MAP file name and name (or list of names) of object (class or package) you want to generate source code for.
7. Customization of generated code
   Generator supports merging of the generated code into already existing file. You have to follow custom code markup specification to make it possible.

### UML requirements used by MapTool generator

1. Packages
   "FileName" tag is used to specify file name for generated unit. By default generated unit has name p<package name>.pas
2. Classes

- Generator automatically adds 'T' in the front of class name, so use bare class names in the UML model.

- "FileName" tag is used to specify file name for generated unit. By default generated unit has name u<class name>.pas.

- The following stereotypes are supported

- Blank (no stereotype) -descendant of TdbItem class

- <<Aggregated>> - descendant of TdbAggregate class

- <<Enumeration>> - regular Pascal enumerator type

- <<Collection>> - not supported

3. Attributes

- Attribute type can have simple data types only. The following types are recommended -

- String

- Integer

- Boolean

- Double

- Date (generated as TDateTime)

- Class properties of class, enumeration and enumeration sets types must be represented by associations!

- <<PK>> stereotype marks attribute as part of class primary key.

- Empty get/set methods will be generated for derived attributes.

4. Associations

- Opposite role with nonblank name and singular cardinality generates object reference (or enumerator property in the case if referenced class has <<Enumeration>> stereotype).

- For compatibility, in current version non-aggregated adjacent role are processed as aggregated. Next versions should ignore such roles.

- Shared adjacent role generates property of object type based on simple object reference. Class doesn't instantiate copy of the referenced entity.

- Aggregated adjacent role generates property of object type based on owned object reference. In addition, reference key attribute(s) is generated. Class instantiates it's own copy of the referenced entity. Property assignment is implemented as creation of referenced entity clone. On application level property assignment can be executed as explicit property assignment or as assignment of reference key values.

- <<PK>> stereotype of the opposite role adds primary keys of the referenced class to the primary key of adjacent class.

- The role name has format of <property name>:<type casting>:<key attribute name>. <Type casting> and <key attribute name> are optional. By default MapTool generates reference keys with format <referenced class name>_key_<PK attribute name> and object reference properties of the opposite class type.

- Opposite role with nonblank name and plural cardinality generates property of TdbCollection type (or enumeration set property in the case if the referenced class has <<Enumeration>> stereotype).

- Class always owns collection and collection elements (adjacent role aggregation is ignored).

### Custom code specification

In many cases you make changes in your generated code and want do not lose such custom modification after code is regenerated. "Custom block" methodology is used for that. Custom block is block of text marked by "//<" and "//>" marks and has a name. You must to put empty blocks with unique names in your templates at any place where custom modification is acceptable. Before save operation the generator reads each block from old file and insert it's contents into newly generated code at proper location identified by the block's name.You must make changes in dedicated "custom" blocks (marked by //< and //>) only.