Lesson 3: Create and refine a class-to-class mapping declaration
About this task
For each mapping declaration in the mapping model, the transformation authoring framework generates a Java™ source file with the name nTransform.java, where n represents the name of the mapping declaration. Collectively, these Java files compose the transformation code. In addition to generating the implementation code for the transformation, the transformation authoring framework also generates code to register the transformation with the transformation service. After you create a mapping declaration, you can incrementally add mapping rules and generate the source code, or implementations, for the mapping rules. You do not have to define all mapping rules before generating the source code.
Mapping declarations typically follow a naming convention of x2y, where x represents the input object type and y represents the output object type. For example, a mapping declaration named Package2EPackage specifies a mapping declaration that has Package as an input object, and EPackage as an output object.
A map between elements establishes the correspondence between their attributes, which permits the exchange of data between them. Most maps provide the ability to further manipulate the data between the source and target. For example, you might choose to specify calculations or make other modifications to the data by creating custom code, which enables you to assign values to the target.
To create a class-to-class mapping declaration in the mapping model:
- If it is not open already, in the Package Explorer view, in the model folder, double-click the .mapping file.
- In the transformation mapping editor, in the Mapping Root section, right-click Generalize_Classes; then click Create Map.
- In the New Map window, in the Map name field, type Class2Class; then click OK. The map is displayed in the Outline view, and opens in the editor area under the Mapping Root section.
Add input and output objects to the class-to-class mapping declaration
About this task
To add an input object and an output object to the class-to-class mapping declaration:
- Click the Add an input object icon, which
is the leftmost icon on the toolbar for the map that you are editing:
- In the Add Input window, in the Element pane, select a metamodel object. The Element pane displays the elements in the metamodel or metamodels that you specify as the source or target for the mapping model. For this tutorial, in the Element pane, expand uml, click Class, and click OK.
- Click the Add an output object icon, which
is the second icon from the left on the toolbar for the map that you are editing:
- In the Add Output window, in the Element pane, expand uml, click Class, and click OK.
- Click .
Define mapping rules between attributes of the class input and output objects
About this task
After you add the input and output objects to the mapping declaration, you can define the mapping rules between the attributes. Mapping rules, also called mappings, specify how to assign a value to an attribute of an output object, according to the values of the attributes of an input object.
- Create a move mapping rule that creates a class in the target model
You create a mapping rule between the name attribute of the input and output objects. The target class has the same name as the class in the input model; you could also think of this as creating a copy of the class. In a later lesson, you add the mapping operations to the mapping rule.
- Create a submap mapping rule that, for each operation in the class, creates
a corresponding operation in the class in the target model.
You create a submap mapping rule between the ownedOperation attribute of the input and output objects. For each operation in the ownedOperation collection, the generated operation in the target model has the same name and visibility as the operation in the input model.
- A move, also called a simple mapping rule, is the most basic type of mapping rule. The input and output attributes must be compatible data types. Both, or neither, of the input and output attributes have multiple values. For example, select this option if an attribute of the output object is a String and an attribute of the input object can be converted to a String without custom code. This type of mapping rule supports a mapping between one source element or attribute and one target element or attribute.The transformation source code that is generated for a move mapping rule implements a rule that copies the value of one input attribute to one output attribute.
A submap is an invocation of one map from within another map. The submap being invoked can, but need not, be defined in the same mapping file as the map that invokes it. A submap enables you to map a complex type in the input model to a complex type in the output model. The submap that you create can invoke a map that exists in any mapping file. Defining submaps in separate mapping files encourages the reuse of maps; however, creating multiple mapping files might increase project maintenance. Submaps can also include other submaps, which results in a hierarchical structure.Submap mapping rules support the following types of mappings:
- 1-to-1 mappings between input objects and output objects, or between the attributes of the input and output objects
- 1-to-m or m-to-1 mappings between attributes of the input and output objects
- m-to-n mappings between attributes of the input and output objects
You can also create submap mapping rules between the input objects and output objects in a mapping declaration.
For each submap in a mapping declaration, an extractor named getInputFeatureToOutputFeature_UsingMap_Extractor is generated in the containing transform, where InputFeature represents the name of the input attribute, OutputFeature represents the name of the output attribute, and Map represents the name of the mapping declaration.
- This mapping rule type enables you to specify custom
code that calculates the value of an output property. For
example, select this mapping type to set the value of a property in
the output object as equal to the concatenation of multiple input
You can specify semantic refinements by using the Object Constraint Language (OCL) API that Eclipse provides.Custom mapping rules support the following types of mappings:
- 1-to-n mappings between input and output objects, or between attributes of the input and output objects
- m-to-n mappings between input and output objects, or between attributes of the input and output objects
- m-to-1 mappings, where m-to-1
represents one of the following mappings:
- A mapping from a single input attribute, whose multiplicity is set to m, to a single output attribute, whose multiplicity is set to 1
- A mapping from multiple input attributes to a single output attribute
- A mapping from multiple input objects to a single output object
- Inherited maps
- You can create this mapping rule only between an input object and an output
object. An inheriting mapping declaration inherits the mapping rules that are defined in the inherited mapping declaration. You can override inherited mapping rules by defining a mapping rule that has the following qualities:
- The input object property and output object property are the same as the inherited mapping rule.
- The overriding and inherited mapping rules are submap mappings that have matching extractors, or the overriding and inherited mapping rules are both move mappings or custom mappings.
An inherited mapping rule, and the rule or extractor generated from that mapping, maintains the same relative position in the processing order as the overridden mapping rule and its generated rule or extractor.
For each move or custom mapping rule in a mapping declaration, a rule is added to the generated transformation source code. For each submap mapping rule, a content extractor is generated in the transformation source code. When you create a mapping rule, its type is determined by the input and output attributes that you select. For example, if the input and output attributes are compatible primitive types, such as strings or integers, a move mapping rule is specified. If the input and output attributes are complex types, a submap rule is specified. If neither move nor submap are appropriate mapping rule types, a custom mapping rule is specified.
To define the mapping rules in the Class2Class mapping declaration:
- Create a move mapping rule between the name attribute
of the input and output object:
- In the editor area, in the class input object, click the name attribute.
- Drag the handle of the name attribute to the name attribute in the class output object.
- Create a submap mapping
rule between the ownedOperation attribute of the input and output
- In the editor area, in the class input object, click the ownedOperation attribute.
- Drag the handle of the ownedOperation attribute to the ownedOperation attribute in the class output object. Because the ownedOperation attribute is a collection, a submap mapping rule is created by default.
- Click .
Create an operation-to-operation mapping declaration
About this task
At this point in the lesson, in the editor area, the submap has an adornment with a red circled X, which indicates an error. Put the mouse pointer over this adornment to view the error message. The error message states that you must select a mapping declaration for the submap mapping rule to invoke. To resolve this error, create an operation-to-operation mapping declaration.
To create an operation-to-operation mapping declaration:
- If the Properties view is not open, in the editor area, right-click the submap element that you created in the previous section, in step 2, and click Show in Properties.
- In the Properties view, on the Details tab, beside the Map field, click New.
- In the New Map window, in the Map name field, type Operation2Operation.
- If the Input field does not contain a value of Operation, click Browse and, in the Add Input window, in the Element pane, click Operation.
- If the Output field does not contain a value of Operation, click Browse and, in the Add Output window, in the Element pane, click Operation.
- Click OK. The error adornment is removed, and the operation-to-operation mapping declaration is displayed in the Outline view. In a later lesson, you create mapping rules in this mapping declaration.
- Click .