## Map Tool application usage

MapTool application is used to

- extend UML class model with object/database mapping information
- execute generation of source file based on UML model, mapping information and generator template

The main window contains

- hierarchical representation of the class model (tree view on the left)
- Two tabs with mapping information (for Oracle and ODBC database)
- Tab with result of generation
- Three tabs with warning, error and trace messages

MapTool application works with "project". Project contains all information necessary for mapping and generation. Projects are stored in files with ".map" extentions. The next dialog representing project properties is available when you create new project, or request properties of the opened one.
Properties

- Generator Template. Main template used by generator. Required.
- Filter Template. Filter template used by generator. Required if your main template uses filter expressions.
- Filter Codes. List of filter codes used by generator. Required if your main template uses filter expressions.
- UML source. Source of UML class model information. Required.
  It can be

- XML file(s) following the XMI specification
- Connection information for Enterprise Architect repository.

- Package. Default package automatically selected every time project has been opened. Can be set only on main form. Optional.
- Repository. Mapping repository. Required if you need to extend UML model with mapping information.
  Repository can be located at

- Oracle database
- Local file

- Oracle Connection. Identifies connection for Oracle database where your classes should be mapped to. Required only if you going to map classes to the Oracle database tables.
- ODBC Connection. Identifies connection for ODBC database where your classes should be mapped to. Required only if you going to map classes to the ODBC database tables.

Additionally application is parametrized by set of options available for configuration via following dialog
Options

- Show Not Mappable Attrs. To show not mappable attributes on a mapping list view.
- Show Result of merging. To show dialog after result is merged into existing file.
- Show details of loading. To show model loading process on the Messages tab.
- Replace Merge.
- Use VSS.
- Columns. List columns to show on the mapping list view.

- Class
- Attribute
- Data Type
- Map
- Map Value
- Map Info
- Map User

- Max line length. Generator parameter identifies the maximum length of line. If generated line exceeds the limit, generator wraps it onto the next line.

Mapping
MapTool extends the UML model with a DB/Object mapping information. The mapping information differs for different aspects of the model -

- Classes can be assosiated with (mapped to) DB tables and views.
- Class attributes can be associated with table or view columns.
- Associations between two classes are treated depends on cardinality and class stereotypes. Each association is considered two times - from perspective of source class and from perspective of destination class. Direction is ignored. From class perspective the only opposite class role and cardinality are important. If opposite role has no name it is ignored.

- If opposite role is plural (0..*, 1..*, *)

- If opposite class has "Enumeration" stereotype
  Association is treated as a Set of Enumerators. Each attribute of opposite class can be mapped to a column. Combination of column values defines the Set.
- If opposite has no stereotype
  Association is treated as a Collection of Objects of opposite class type. Three string values can be associated with collection - for select, insert and delete statements.

- If opposite role is singular (0..1, 1)

- If opposite class has "Enumeration" stereotype
  Association is treated as an enumerator. In addition to the column mapping, each attribute of the enumerator can be associated with particukar column value. As result, the value in the mapped column defines the value of the enumerator.

- If opposite has no stereotype
  Association is treated as an Object Reference. It can be mapped to a table column. Column value is considered as foreign key to the target object.

Each mapping to a table column keeps information about column datatype.

### Mapping Strategies

Mapping strategies depend on type of model element, database structure and mechanism of mapping generation used in generator template. The are always one available strategy - NOMAP, which means that mapping is hardcoded maually in the source code after process of generation. You can mix different strategies for different model elements; just make sure your generator template complies with used set of strategies.

- Classes can be mapped to DB tables or views.

- Cls.NoMap.
- Cls.Map. Map only non-enumerator classes.
  Path package\class; Map=table_name; Value=; Info=;
- Cls.MapX. Map all classes.
  Path package\class; Map=table_name; Value=; Info=;

- Class attributes of simple data types (like string, integer, float, data) can be mapped to table or view columns.

- Attr.NoMap.
- Attr.Map.
  Path package\class\AttrName; Map=column_name; Value=; Info=column_type

- Class attributes of enumerator types can be mapped to table or view columns. Additionally mapping should provide value coding/decoding information. In UML model property of enumeration type can be represented as regular class attribute or as association between the class and another class representing enumerator class. Typically such target class has stereotype <enumerator> or <enumeration>. Value mapping can be done in context of attribute of original class (local value mapping) or in context of target class.

1. If enumeration property is presented as class attribute the are two options

- Enum.NoMap.
- Enum.ValList. User managed list of pairs "code" - "value" in context of attribute of original class.

2. If enumeration property is presented as association between classes there are follwoing options

- Enum.NoMap.

- EnumValList. User managed list of pairs "code" - "value" in context of attribute of original class.
- Enum.DbVal.
- Enum.Global. Providing values for each attribute of target (enumerator) class in context of target class.
  Path package\enumClass\enumAttrName; Map=; Value=Code; Info=
- Enum.Local. Providing values for each attribute of target (enumerator) class in context of attribute of original class.
  Path package\class\AttrName\enumAttrName; Map=; Value=Code; Info=

- Class attributes of boolean type can be considered as case of enumerator type. Becouse UML model usually doesn't provide class "Boolean", MapTool can automatically create such class (with "enumerator" stereotype), place it in the root package and emulate association between original class and such pseudo class instead of each attribute of boolean type. If it is not desired, use value coding in the generated source code.

- Bool.NoMap.
- Bool.ValList.
- Bool.Global.
  Path RootPackage\Boolean\True|False; Map=; Value=TrueCode|FalseCode; Info=
- Bool.Local.
  ???? Path package\class\AttrName; Map=; Value=Code; Info=

- Class attributes of enumeration set type (Pascal terminology). Mapping strategy depends on the way such values are represented in DB structure.

1. Single column. Examples are - integer value storing bit mask and stirng value storing list of codes. Possible strategies are

- Set.NoMap.
- ?
- Set.Local1. Available only in case of representation of enumerator type as UML class. Mapping provides the column name in context of role and original class.
  Path package\class\RoleName; Map=column_name; Value=; Info=column_type

1. Set of columns for each possible enumerator value.

- Set.NoMap.
- Set.List.
- Set.DbVal.
- Set.GlobalX. Available only in case of representation of enumerator type as UML class. Mapping provides column names in context of target class and attributes.
- Set.LocalX. Available only in case of representation of enumerator type as UML class. Mapping provides column names in contextex of target class attributes and the original class.

- Associations between classes with singular multiplicity on the end represent properties of "pointer to class" type. Note - role on the association end plays as property of the class on the opposite end. Such properties can be mapped to table or view column(s).

1. Ref.NoMap.
2. Ref.Map. Mapping is done for the role in context of original class. Suitable if all classes have simple primary keys (is mapped to the single column).
   Path package\class\RoleName; Map=column_name; Value=; Info=column_type
3. Ref.KeyMap. If target class has combined primary key (is mapped to two or more columns) the mapping must provide several mapping values, one per each primary key attribute of target class.Simple keys can be mapped with such strategy also. Mapping is axecuted in context of original class and the role.
   Path package\class\RoleName\RefClassKeyName; Map=column_name; Value=; Info=column_type

- Associations between classes with plural multiplicity on the end represent properties of "collection" type. Note - role on the association end plays as property of the class on the opposite end. Two strategies are available

1. Coll.NoMap.
2. Coll.SQL4. Four SQL statement information. Mapping requires at least one select SQL statement and, optionally, insert, update and delete SQL statements.
   Path package\class\RoleName; Map=; Value=; Info=select,insert,update,delete