Tutorial: Model-to-Model Transformation

In this tutorial you will learn how you can define a transformation from a source model conforming to a EMF meta model to a target model conforming to another EMF meta model with EMorF. In particular a class diagram will be transformed to a database schema. This is a typical example for a model-to-model transformation. Before you start please ensure that you have installed EMorF.
You can also download the resulting EMorF project here.

Start Up

Before you can start to define the transformation itself, you need the EMF based meta models first.

classdiagram database
You can get the models when you download the resulting EMorF project file or create them with EMF.

The next step is to create a container for the EMorF files. Thus create a new project with the name "org.emorf.tutorial.modeltransformation". You can create a new project when you select File>New>Project...>General>Project.

Now open the context menu of the newly created project, select New>Other>EMorF>EMorF Files and press Next. Then change the name of the EMorF model file to "class2database-rules.emorf". This file contains all transformation rules.
When you press Next again change also the name of the diagram file used to specify one transformation rule graphically to "Package2Schema.emorf_diagram". This name is also used as name for the first transformation rule in the EMorF model.
When you press Next again you have to define finally on which meta models the transformation rules are based. Press the Browse Workspace Button and select the class meta model file (classdiagram.ecore). Now select the check button Add target domain models and add also with help of the newly enabled Browse Workspace button the database meta model file (database.ecore). Then press Finish.
A new EMorF rule editor should have been opened now. The editor shall look like in the following image. EMorF Transformation Rule Editor The editor is split into three parts. In the left part elements of the source meta model (class diagram), in the right part elements of the target meta model (database) and in the middle part trace elements must be added. On the left you can see the tool palette used to create elements. The tool palette contains an expression node, a link node, all class elements of the classdiagram meta model, a trace element and all class elements of the database meta model.

Create your first EMorF transformation rule

Select now the package class node of the classdiagram meta model on the tool palette and drop it to the left part of the rule, called "source-domain". After a blue node is created you have to give the node a name, for example "pack". The created node is a so called pattern node. If you select it you can see the properties of this element in the properties view. A pattern node has not only a name, but also a reference to the eclass called "Package" defined in the classdiagram meta model. With the modifier kind you can select if a node shall only be bound or also created or deleted. Lets leave this node and create another one.

Select the node called "Schema" at the tool palette and add it to the part called "target-domain".
Give the node also a name.

Then create a trace node on the part called "corr-domain". This node references to the eclass called "TraceInstance" included in the trace meta model EMorF already provides. With pattern links between the trace node and the other node you can define what trace information will be created. Select the node called "Link" at the tool palette and add it from the trace node to the package node. Then a dialog will be opened with possible reference types for the pattern link. Please select the reference type "sources" and press OK. When you select the created link you can see in the properties view, that a link also has a name, a modifier and a type. This time the type of the link is the reference called "sources" defined in the trace meta model. Select again the node called "Link" at the tool palette and add it from the trace node to the schema node. Please select in the opened dialog the reference type "targets" and press OK.

To specify a transformation form a package element of the classdiagram to a schema element of the database correctly you need to change the modifier of the trace node and schema node to "create" in the properties view. Furthermore we need to specify that this rule is the starting point of the transformation. Please select the top field of the diagram editor, where you can see the name of the rule and set the value of the rule property called "Top Level" to "true". The created EMorF files should be valid now.

To also assign the name of the package to the name of the schema, you need to add an expression node. Select the expression node in the tool palette and add it to the "target-domain". Now, you have to add an OCL expression to the expression node. We want that the created schema shall have the name of the package. So the expression shall look like: "schema.name = pack.name". Change the expression kind in the properties view to "assignment". Please save the rule.

Check now if the created rule looks like in the following image.

Package2Schema rule

Apply your first EMorF transformation rule

To apply this rule on an instance model of the class diagram meta model create at first a dynamic instance model of the class diagram model with a package object included.

Transformation Run Configuration Then open the context menu of the EMorF model file (.emorf) and select Run As>Run Configurations.... Open the context menu of the item EMorF Execution and select New. Select the EMorF model file with help of the first Browse... button. Then select the execution mode forward and define the paths of the source and target model files. The source model file shall be the created instance model. Select the path with help of the Browse... button. The target model file will be created by the transformation execution. Finally, define a path for the trace file (please use the file extension .engine), which also will be created, and press Run.

Check now the created files. In the target file there should be a schema object with the name of the package. In the trace file there should be an object called "TransformationInstance" with a child object called "TraceInstance" with the source and target references you specified.

Create further EMorF transformation rules

Now we want to define the transformation from a class object of the class diagram meta model to a table object of the database meta model. Select the EMorF model file and open the context menu. Select the item Add New EMorF Rule. Give the new diagram file a name (for example "Class2Table.emorf_diagram") and press Finish. Note again, the rule will have the same name in the EMorF model. Now again a new diagram editor was openend. Please remodel the following rule. class2table-rule This rule specifies that each class node in a package node shall be transformed to a new table of the corresponding schema object with a name equal to the class name. Furthermore a trace object between the class and table node shall be created. Please save the rule.

To create a further EMorF rule, select again the EMorF model file, open the context menu and select the item Add New EMorF Rule. With the rule we want to specify the transformation from an attribute object of the class diagram meta model to a column object of the database meta model. So give the new diagram file for example the name "Attribute2Column.emorf_diagram" and press Finish. Please remodel the following rule. attr2column-rule This rule specifies that each attribute node in a class node shall be transformed to a new column of the corresponding table object with a name equal to the attribute name. Furthermore a trace object between the attribute and column node shall be created. You see the trace objects are reused to get the corresponding objects in the target model. Please save the rule.

Now add to the instance model class and attribute objects and check, what happens when you run the transformation again. Select the EMorF model file, open the context menu, select the item Run As and then the item EMorF Execution. In the target file should also be table and column objects. In the trace file should be additional trace objects.

Define bidirectional EMorF transformation rules

To may use EMorF rules for both transformation directions, we need to change the rules a little. In the following image you can see how the "Package2Schema" shall look like. bidirectional package2schema-rule The differences to the rule before are contained in the "source-domain". First the modifier of the package node changed to "create". Second there is a further expression node which defines the assignment to be executed when a package object shall be created based on a given schema object. The transformation engine automically interprets the rules correctly based on the given direction.

Please change also the "Class2Table" and "Attribute2Column" rules.
They should look like the rules in the following images. bidirectional class2table-rule bidirectional attribute2column-rule The differences to the rules before are also contained in the "source-domain". First the modifier of the class node and attribute node changed to "create". Second there are further expression nodes which define the assignment to be executed when a class object shall be created based on a given table object or a attribute object shall be created based on a given column object.

Now check, what happens when you run the transformation in reverse direction. Delete the source file, before. Then select the EMorF model file, open the context menu, select Run As>Run Configurations... and change the execution mode to reverse. The newly created source file should look like before.

Explore the trace model

When you open the trace model with the EMorF Trace View and select the tab Trace View you can see the traces in a table view like in the following image. With this editor you can retrace which concrete object element of the target file corresponds to a concrete element in the source file and back again. You have just to select one element. The selection of the other elements will be updated automatically. EMorF Trace View

Finish

Wow, that was a journey, wasn't it? Now its time for a break. You finished this tutorial and know now how to specify model transformation rules with EMorF. Thank you for joining this journey. If you have any questions or any comment, don't hesitate to contact us.

© 2012 Solunar GmbH. All Rights Reserved. | Imprint