Tutorial: Model Modification

In this tutorial you will learn how you can define modifications on models conforming to a EMF based meta model with EMorF. In particular in this tutorial model modifications on the extended library model, contained in the EMF examples, are specified with EMorF. Before you start please ensure that you have installed EMorF.

Start Up

At first you need the EMF based meta model of the library model. You get it when you select File>New>Example>Eclipse Modeling Framework>Extended Library Model Example, press Next and then Finish. In your workspace three new projects (called org.eclipse.emf.examples.library, org.eclipse.emf.library.edit, org.eclipse.emf.examples.library editor) should be contained then.

The next step is to create a container for the EMorF files.
Thus create a new project with the name "org.emorf.tutorial.modelmodification". 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 please the name of the EMorF model file to "library-modifications.emorf". In this file all modifications rules will be stored.
When you press Next again change also the name of the EMorF diagram file to "CreateBook.emorf_diagram". This file is used to specify one modification rule graphically. The name of the diagram file is also used as name for the modification rule.

EMorF File Creation Wizard

When you press Next again you have to select finally on which meta model the modification rules shall be defined. Press the Browse Workspace button and select the library meta model file (org.eclipse.emf.examples.library/model/extlibrary.ecore). Then press Finish.
A new EMorF rule editor will be opened. Within this editor you can start to define model modifications graphically.

Create your first EMorF rule

Now we want to create a new book in the library with help of a EMorF rule. The EMorF rule is shown in the following image. CreateBook rule After you have created the initial EMorF files you have maybe already seen that there must be an error in the created diagram file. That is true. There is a validation error. In each EMorF rule at least one element must be contained. So add an element to the EMorF rule to get a valid file. Use the tool palette of the diagram editor. The tool palette, shown on the left in the above image, contains an expression node, a link node and all elements of the library meta model.
Please add the node called "Library" to the rule. After a blue node is created you have to give the node a name, for example "library". You see the diagram file is now valid.
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 type reference to the class called "Library" from the library meta model. The modifier of a pattern node defines if the node shall just be bound or also created or deleted.

Now add also a "Writer" and "Book" node to the rule. Give the first node the name "writer" and the second the name "book".

Then create a link between the library and the writer nodes. Select the node called "Link" at the tool palette and add it from the library node to the writer node. When you select the link you can see in the properties view, that a link also has a name, a modifier and a type. The type of the link called "writers" is the link type defined in the meta model between the class "Library" and the class "Writer".

Please add also a new link from the library to the book node. You can also use the model assistant to create a link. The model assistant for links is represented by two little arrows shown in the following image. Select the outgoing arrow of the library object and drag it to the book object.

Model Assistant
Because between a library and a book more than one reference is defined in the meta model, a dialog pops up then. Please select the reference type called "stock". This is required, because this is the containment reference between the library and a book. It must be created when we want to add a new book to a library.

Now add a link from the book node to the writer node.

Finally, please change the modifier of the pattern node with the type "Book" in the properties view from "bind" to "create".
The node, the outgoing and incoming links should be now green colored. The modifier of the links is automatically set to "create".

Now save the rule and check if your rule looks like in the image.

Apply your first EMorF rule

To apply the created rule on an instance model of the library meta model, create at first a dynamic instance of the class "Library" with two writers.

Then, please select Window>Preferences>EMorF>Interpreter, press New and select the EMorF model file you have created (extension .emorf) and press OK.

Now select the library object of the instance model and open the context menu. Select Interpreter>Apply and then your new rule. Your rule will be applied to the instance model with the selected library object as first matching candidate.

Check now with the newly opened dialog the result of the rule application. When you for example select the object after Matching>Objects>writer like shown in the following image, in the tree editor, where the library instance is shown, the writer object bound by your rule is also selected.
If you want to define the concrete writer, who should be the author of the new book, select the concrete writer and apply the rule again. Please save your modified instance model. Rule application result

Delete model elements with a EMorF rule

Now we want to delete books contained in the library instance model with a EMorF rule. Select the EMorF model file (library-modifications.emorf) and open the context menu. Select the item Add New EMorF Rule. Give the new diagram file a name (for example "DeleteBook.emorf_diagram") and press Finish.

Please open the last created rule ("CreateBook").
Select all elements and copy them.

Paste and layout the elements in the new rule and change the modifier of the book node to "delete".

Now save the rule and check again, what happens when you apply this rule to the existing instance model. Open the instance model. Select the library object, a book object or a writer object. Open the context menu and select your rule after Interpreter>Apply. A book with the defined links should be deleted.

Constraints and Assignments

Now we want to create a book with the title "EMorF" to a writer called "Wagner". To do this, we have to use also expression nodes. Extend the already existing "CreateBook" rule. So please open the corresponding diagram editor.

Now add an expression node to the rule and enter the OCL expression "writer.lastName = 'Wagner'". With this expression you define the constraint, that the bound writer shall have the last name "Wagner".

Now add a further expression node to the rule and enter the OCL expression "book.title = 'EMorF'". This is an assignment expression. To define it as such, change the kind of the expression node in the properties view to "assignment". You defined now that "EMorF" is the title of the newly created book.

Now save the rule and check again, what happens when you apply this rule to the existing instance model. Open the instance model and select the library object. Then open the context menu and select your rule after Interpreter>Apply. If in the instance model a writer with last name "Wagner" exists, a new book with the title "EMorF" should be created. If not, there should be opened a dialog with the Message "Command executed! Matching incomplete.".

EMorF rule with Parameters

Now create a book with a title, defined by a rule parameter, to a writer, whos last name is also defined by a parameter. To do this, you have to define the parameters first. Change again the last created "CreateBook" rule.

Select the diagram background, which represents the EMorF rule, and open the properties view. Then select the Tab Parameters and add, by pressing the button with a plus, a parameter with the name "writerName" and the type "EString". Change also the constraint expression "writer.lastName = 'Wagner'" to "writer.lastName = writerName".

Then define a second parameter with the name "bookTitle" and the type "EString" for the rule and change also the assignment expression "book.title = 'EMorF'" to "book.title = bookTitle".

Rule with parameters Now save the rule and check again, what happens when you apply this rule to the existing instance model. Open the instance model. Select the library object. Open the context menu and select your rule after Interpreter>Apply. A dialog should be opened, where you can define the concrete values of the parameters. If you then press OK a new book with the defined title should be created if a writer with the defined last name exists.

Create a Run Configuration

You can also run one modification rule on a given instance model with help of a run configuration, if you dont want to select the options of a rule application over and over again. To define a run configuration, open the context menu of the EMorF model file (.emorf) and select Run As>Run Configurations....

Then open the context menu of the item EMorF Execution and select New. EMorF Configuration Page Select now in the newly opened configuration page at first the EMorF model file, where the rule you want to apply is stored in, with help of the first Browse... button. Then select the rule you want to apply. If the rule has parameters enter also concrete parameter values. Define then on which instance model the rule shall be applied with help of the second Browse Workspace button. Finally select a concrete object of the instance model, which shall be the first matching candidate, and press Run. The rule will be applied.

You can also use the Preview button to get a differences view between the current instance model and the instance model after rule application.

Finish

Congratulations! You finished this tutorial and know now the basic concepts to may specify model modification rules with EMorF. Thank you. If you have any questions or any comment, don't hesitate to contact us.

© 2012 Solunar GmbH. All Rights Reserved. | Imprint