< Previous | Next >

Lesson 3: Create and refine a class-to-class mapping declaration

This lesson shows you how to create a mapping declaration that specifies a UML class as both the input and output object. This class-to-class mapping declaration contains mapping rules that, when you run the generated transformation, create a copy of the class and its operations in the source model and places the copy in the target model. You also create an operation-to-operation mapping declaration, which the submap in the class-to-class mapping declaration invokes.

About this task

A mapping declaration, also called a map, specifies how to create or update an output object for a given input object. When you author transformations, you can use a mapping declaration to specify how attributes in an input object correspond to attributes of an output object. Each mapping declaration specifies an input type and an output type, which you select from the metamodels that you add to the mapping model.

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:

Procedure

  1. If it is not open already, in the Package Explorer view, in the model folder, double-click the .mapping file.
  2. In the transformation mapping editor, in the Mapping Root section, right-click Generalize_Classes; then click Create Map.
  3. 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

After you create the mapping declaration, you must add an input object and an output object to it. In this lesson, you specify a UML class as the input and output object.
Note: When you create model-to-model transformations, to add an object type that is not available in the input or output metamodel that the map uses, you can add the appropriate UML profiles or Ecore metamodels to the scope of the map. In the Add Input window, click Add Model and specify the appropriate model.

To add an input object and an output object to the class-to-class mapping declaration:

Procedure

  1. Click the Add an input object icon, which is the leftmost icon on the toolbar for the map that you are editing:
    This image shows the Add an input object icon located on the toolbar for the map that you are editing.
  2. 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.
  3. 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:
    This image shows the Add an output object icon which is the second icon from the left on the toolbar for the map that you are editing.
  4. In the Add Output window, in the Element pane, expand uml, click Class, and click OK.
  5. Click File > Save.

Results

You can now define mapping rules between the attributes of the class input and output objects.

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.

In the class-to-class mapping declaration, complete the following steps:
  • 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.

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. You can create multiple mapping rules between the input and output object and, as a later lesson in this tutorial demonstrates, you can also create multiple mapping rules between an attribute of an input and output object. You can create the following types of mapping rules:
Move
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.
Submap

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
If the submap rule specifies a 1-to-m mapping, the generated transform appends an object from a singleton attribute to a list; for an m-to-1 mapping, the transform extracts an object from a list and inserts it into a singleton attribute.

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.

Custom
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 object properties.

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.
If you create an inherited maps mapping rule, you must specify the mapping declaration that contains the mapping rules that you want to inherit. You cannot specify more than one inherited map in a mapping declaration.

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:

Procedure

  1. Create a move mapping rule between the name attribute of the input and output object:
    1. In the editor area, in the class input object, click the name attribute.
    2. Drag the handle of the name attribute to the name attribute in the class output object.
  2. Create a submap mapping rule between the ownedOperation attribute of the input and output object.
    1. In the editor area, in the class input object, click the ownedOperation attribute.
    2. 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.
  3. Click File > Save.

Results

You can now create the operation-to-operation mapping declaration.

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:

Procedure

  1. 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.
  2. In the Properties view, on the Details tab, beside the Map field, click New.
  3. In the New Map window, in the Map name field, type Operation2Operation.
  4. 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.
  5. 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.
  6. 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.
  7. Click File > Save.

Results

In the next lesson, you define a class-to-interface mapping declaration.
< Previous | Next >

Feedback