IncQuery integration into Sirius

• Download the Eclipse Modeling Tools Luna-SR2 release (http://www.eclipse.org/downloads/ ; it's possible that the tool will work with other Eclipse releases, but it was only tested with the above mentioned release)
• From the Eclipse Marketplace install the followings (it's possible that the tool will work with other versions, but it was only tested with these)
• EMF-IncQuery 0.9.1
• Sirius 2.0
• Clone the Git repository
• Import the projects from the host directory into the host-eclipse
• Generate the followings:
• org.eclipse.incquery.viewmodel/model/traceability.genmodel->Generate model code
• It can happen, that for some IncQuery patterns the needed classes (Match, Matcher, etc.) won't be generated autmatically. In this case, you have to open the following .eiq files, modify them in a "not harmful" way (e.g. insert and delete a space character), and after that save the files. These steps ensure that the needed files will be generated.
  • The .eiq files in the hu.bme.mit.inf.dipterv1.incquery/src/hu.bme.mit.inf.dipterv1.incquery.patterns/ package
  • The .eiq files in the hu.bme.mit.inf.sirius.interpreter.incquery/src/hu.bme.mit.inf.sirius.interpreter.incquery.traceability.patterns package
  • The .eiq files in the org.eclipse.incquery.viewmodel/src/org.eclipse.incquery.viewmodel.traceability.patterns package
• Create a new Run configuration (type: Eclipse Application, the default settings will be fine)
• Run the Runtime Eclipse
• Import the projects from the runtime directory into the runtime-eclipse
• Switch to Modeling perspective
• You can find some instance model in the following projects
• hu.bme.mit.inf.eclipsecon.sample
• hu.bme.mit.inf.socialnetwork.base.sample

First of all I would like to describe some projects in the host-eclipse, which are important in aspect of usage:

• hu.bme.mit.inf.dipterv1.models: this project contains the metamodels which are used during the transformation (model directory). For the demo we will use the socialnetwork_base and socialnetwork_many_one metamodels.

• The socialnetwork_base metamodel: with this metamodel we can describe "family trees". In the instance model we can create Man or Woman elements, and we can define "parent-child" relationship (children reference) and "friend" relationship (friends reference) between them. Every person has some further attribute: first name (firstName attribute), last name (lastName attribute), age (age attribute), etc.

• The socialnetwork_many_one metamodel: with this metamodel we can describe families, and "friend" relationship between them. The Family element has a name attribute too.

• hu.bme.mit.inf.dipterv1.incquery: this project contains the IncQuery patterns that are used during the transformation. With these patterns we can define transformations between the socialnetwork_base-type and socialnetwork_many_one/one_many/etc-type models. The patterns were grouped into the same file depending on the transformation. For example if the patterns are used to create a model with the social_network_many_one metamodel, then the patterns will be found in the patterns_many_one.eiq file (we'll use these patterns in the example: see hu.bme.mit.inf.eclipsecon.sample project). From this file, I would like to highlight two patterns:

• family: we can find the "families" in the source instance model with this pattern

• friend: we can find the "friend relationships" between the families with this pattern

• IMPORTANT: EVERY PATTERN, THAT WE WANT TO USE FOR DEFINING A SIRIUS-BASED EDITOR HAVE TO BE DEFINED IN THIS PROJECT. THESE PATTERNS HAVE TO BE PLACED INTO A SUITABLE .eiq FILE LIKE I DESCRIBED ABOVE. THE USED PATTERNS MUST BE PUBLIC!

In the followings, I will describe some project in the runtime eclipse:

• hu.bme.mit.inf.socialnetwork.base.design: this project contains the definition of the Sirius-based editor for the source model.

• hu.bme.mit.inf.socialnetwork.manyone.design: this project contains the definition (/description/socialnetwork_manyone.odesign) of the Sirius-based editor for the target model (or view model) of the transformation. If you open the .odesign file, at the properties of the Social Network Many-One Diagram element (Properties View) on the Advanced tab you will see a field, called Root Expression. The expression, that you can see here (incquery:init[packageNS=http://hu.bme.mit.inf.models/socialnetwork_many_one]) is a special initialization instruction, which makes the inicialization of the tools for the transformation when the diagram opens. The packageNS parameter is used to set that metamodel's namespace URI, which belongs to the target (or view) model created during the transformation. In the other parts of the file you can find the mappings (Family element, Friend edge). At the properties of the Family element on the General tab you can see a Semantic Candidates Expression field with this expression: incquery:hu.bme.mit.inf.dipterv1.incquery.patterns.family. Because of this expression, the tool will create a Family element (the type of the created element is set in the Domain class field) in the view model for every match of the pattern with the given FQN. The created elements will be displayed in the editor (the properties of the created elements won't be set, so in this example the name of the family (name attribute) will be empty). Of course, every time, when a match disappears, the corresponding Family element will be deleted from the view model. With the Friend element, we can create edges between two Family element. If you open the properties of it, on the General tab you will see a Target Finder Expression field, with this expression: incquery:hu.bme.mit.inf.dipterv1.incquery.patterns.friend[ref=friends]. Because of this expression, the tool will create an edge (set the friends relation) between the corresponding Family elements for every match of the pattern with the given FQN (if you examine the family pattern, you can see that a family is identified by a man-woman pair, who have at least one common child, and don't have any ancestors; the friend pattern gives four parameters: two man-woman pairs (families); if the friend pattern matches, the first two parameter represents the family, from which the edge starts, while the second two parameters represents the family where the edge ends). For those patterns, which belongs to edges (in this example the friend pattern) you have to define the parameters as follows: parameters of the source element's pattern, parameters of the target element's pattern (in this example on both ends of the edge we have a Family element, so we created the friend pattern with the parameters: family pattern's parameters, family pattern's parameters).

• hu.bme.mit.inf.eclipsecon.sample: this project contains an example for the demonstration. If you open this project in Modeling perspective you will see a sample.socialnetwork_base file (this is a sample source instance model). If you open this model, under the Social Network element you will find two diagrams: new Social Network Base Diagram, new Social Network Many-One Diagram. If you open the former, you will see the source model of the transformation, while if you open the second one, you will see the view model created by the transformation.

• IMPORTANT: THIS IS A BETA VERSION OF THE TOOL, SO IT CAN CONTAIN BUGS. THE MODIFICATION OF THE SOURCE MODEL WITH THE GIVEN TOOLS IN THE EDITOR IS POSSIBLE, THE CORRESPONDING VIEW MODEL WILL BE AUTOMATICALLY MODIFIED. THE UNDO OPERATION DOES NOT WORK PROPERLY, USING IT IS NOT RECOMMENDED.

• Eclipse Modeling Tools letöltése (http://www.eclipse.org/downloads/ ; én a Luna-SR2 verziót használtam ; biztos-ami-biztos azt javaslom, hogy a demóhoz egy teljesen különálló, másra nem használt eclipse-t készítsünk el, nehogy más projektekkel/pluginekkel összeakadjon az eszköz)
• az Eclipse Marketplace-ből telepítsük az alábbiakat (elképzelhető, hogy a lentiektől eltérő verzióval is működni fog az eszköz, viszont tesztelve ezekkel volt)
• EMF-IncQuery 0.9.1
• Sirius 2.0
• Git repository klónozása
• a host mappában lévő projekteket importáljuk be a host-eclipsebe
• a szükséges részeket generáljuk le:
• org.eclipse.incquery.viewmodel/model/traceability.genmodel->Generate model code
• előfordulhat, hogy az egyes projektekben található IncQuery mintákhoz nem generálódnak le automatikusan a szükséges osztályok (Match, Matcher, stb.). Ezt úgy tudjuk orvosolni, hogy az alább felsorolt csomagokban található .eiq fájlokat megnyitjuk, módosítunk bennük valamit (természetesen úgy, hogy ezzel ne tegyünk kárt a már meglévő mintákban), majd mentünk. Ekkor biztosan legenerálódnak a szükséges fájlok.
  • hu.bme.mit.inf.dipterv1.incquery/src/hu.bme.mit.inf.dipterv1.incquery.patterns/ csomagban található fájlok
  • hu.bme.mit.inf.sirius.interpreter.incquery/src/hu.bme.mit.inf.sirius.interpreter.incquery.traceability.patterns csomagban található fájlok
  • org.eclipse.incquery.viewmodel/src/org.eclipse.incquery.viewmodel.traceability.patterns csomagban található fájlok
• hozzunk létre egy új Run configuration-t (Eclipse Application típusút, az alapbeállítások jók lesznek)
• indítsuk el a Runtime Eclipse-et
• importáljuk be a repository runtime mappájában található projekteket
• váltsunk Modeling perspektívára
• példánymodelleket az alábbi projektekben találhatunk
• hu.bme.mit.inf.eclipsecon.sample
• hu.bme.mit.inf.socialnetwork.base.sample

Először bemutatnám a host eclipse-ben található, a használat szempontjából fontos projekteket:

• hu.bme.mit.inf.dipterv1.models: ez a projekt tartalmazza a transzformáció során használt metamodelleket (model mappa). A demó során ezek közül a socialnetwork_base valamint a socialnetwork_many_one metamodellekre lesz szükség.

• A socialnetwork_base metamodell: családfák létrehozását teszi lehetővé. A modellben lehetnek férfiak (Man) illetve nők (Woman) valamint köztük definiálhatunk szülő-gyermek (children) valamint baráti (friends) kapcsolatokat. Az egyes emberek rendelkeznek továbbá néhány tulajdonsággal is: keresztnév (firstName), vezetéknév (lastName), kor (age), stb.

• A socialnetwork_many_one metamodell: családok, valamint a köztük lévő baráti kapcsolatok leírására alkalmas. A család (Family) rendelkezik továbbá egy név (name) tulajdonsággal.

• hu.bme.mit.inf.dipterv1.incquery: ez a projekt tartalmazza a transzformáció során használható minták definícióit. A minták segítségével transzformációkat írhatunk le a socialnetwork_base típusú valamint socialnetwork_many_one/one_many/stb típusú modellek között. A minták attól függően lettek csoportosítva egy-egy fájlba, hogy a transzformáció során mely metamodell szerinti modell jön létre. Így például a demóban bemutatott több-egy leképzéshez szükséges minták a patterns_many_one.eiq fájlban kaptak helyet. Ebből a fájlból két mintát emelnék ki:

• family: ennek a segítségével találhatóak meg az egyes családok a forrás példánymodellben

• friend: ennek a segítségével találhatóak meg a baráti kapcsolatok egy-egy család között

• FONTOS: MINDEN OLYAN MINTÁT, AMIT A SIRIUS-OS FELÜLET DEFINIÁLÁSA SORÁN FEL SZERETNÉNK HASZNÁLNI, AZT EBBEN A PROJEKTBEN KELL DEFINIÁLNI. A HASZNÁLNI KÍVÁNT MINTÁT A FENTIEK ALAPJÁN HELYEZZÜK EL EGY MEGFELELŐ .eiq FÁJLBA; ÜGYELJÜNK RÁ, HOGY A LÉTREHOZOTT MINTÁKNAK PUBLIKUSNAK KELL LENNIÜK!

A következőkben a runtime eclipse-ben található fontosabb projekteket ismertetem:

• hu.bme.mit.inf.socialnetwork.base.design: ez a projekt tartalmazza a transzformáció bemeneteként szolgáló modell szerkesztéséhez és megjelenítéséhez használható Sirius-os felület definícióját.

• hu.bme.mit.inf.socialnetwork.manyone.design: ez a projekt tartalmazza a transzformáció eredményeként létrejövő modell megjelenítéséhez használható Sirius-os felület definícióját (/description/socialnetwork_manyone.odesign). A fájlt megnyitva a Social Network Many-One Diagram elem tulajdonságainál (Properties View) az Advanced fülön láthatunk egy Root Expression mezőt. Az itt látható kifejezés (incquery:init[packageNS=http://hu.bme.mit.inf.models/socialnetwork_many_one]) egy speciális inicializáló utasítás, melynek hatására a diagram megnyitásakor inicializálódnak a transzformációk elvégzéséhez szükséges eszközök. A packageNS paraméter a transzformáció során létrejövő modell (ún. nézeti modell) struktúráját definiáló metamodell namespace URI-át kapja meg értékül. A fájl többi részében a leképzések találhatóak (Family elem, Friend él). A Family elem tulajdonságait megvizsgálva a General fülön láthatjuk a Semantic Candidates Expression mezőben a incquery:hu.bme.mit.inf.dipterv1.incquery.patterns.family kifejezést. Ez azt a működést produkálja, hogy a megadott FQN-el rendelkező minta minden egyes illeszkedéséhez létrejön egy-egy Family elem a nézeti modellben, mely meg is jelenik a felületen (a létrehozott elem tulajdonságai nem kerülnek kitöltésre, így a példa esetén a család neve sem lesz megadva a létrejött elemeknél). Természetesen minden egyes illeszkedés eltünésekor a megfelelő elem törlődik a nézeti modellből és így a felületről is. A Friend elem segítségével éleket tudunk létrehozni két Family elem között a nézeten. A tulajdonságait megvizsgálva a General fülön láthatjuk a Target Finder Expression mezőben a incquery:hu.bme.mit.inf.dipterv1.incquery.patterns.friend[ref=friends] kifejezést. Ez azt a működést produkálja, hogy a megadott FQN-el rendelkező minta minden egyes illeszkedése esetén behúz egy-egy élt a megfelelő Family elemek között (ha megvizsgáljuk a family mintát láthatjuk, hogy a forrásmodellben egy családot egy-egy olyan férfi-nő párossal azonosítunk, akiknek van közös gyerekük és nincsenek őseik; a friend minta összesen négy paramétert ad: két férfi-nő párost, vagyis két családot; ha a friend minta illeszkedik, annak első két paramétere az él kiindulópontjaként szolgáló családot reprezentálja, míg a második két paraméter az él végpontjaként szolgáló családot reprezentálja). Megkötés az élekhez tartozó minták esetén, hogy a minta paramétereit az alábbiak szerint kell megadni: forrás elemhez tartozó minta paraméterei, cél elemhez tartozó minta paraméterei (a friend minta esetén az él mindkét végén Family elem volt, így a family minta paramétereit kellett megadnunk kétszer egymás után).

• hu.bme.mit.inf.eclipsecon.sample: ez a projekt tartalmaz egy példát a működés bemutatásáhot. Modeling perspektívában megnyitva a projektet találunk egy sample.socialnetwork_base fájlt, melyet "lenyitva" a Social Nwtwork elem alatt találunk két diagrammot: new Social Network Base Diagram, new Social Network Many-One Diagram. Előbbit megnyitva a transzformáció bemeneteként szolgáló modellt láthatjuk, míg utóbbit megnyitva a transzformáció során létrejövő nézeti modellt tekinthetjük meg.

• FONTOS: AZ ESZKÖZ MÉG NEM VÉGLEGES, TARTALMAZHAT HIBÁKAT. A FORRÁSMODELL MÓDOSÍTÁSA A FELÜLETEN DEFINIÁLT ESZKÖZÖKKEL LEHETSÉGES, A MÓDOSÍTÁSOK HATÁSÁRA -AMENNYIBEN SZÜKSÉGES- AUTOMATIKUSAN MÓDOSUL A HOZZÁ TARTOZÓ NÉZETI MODELL IS. NEM MŰKÖDIK VISZONT MEGFELELŐEN A VISSZAVONÁS MŰVELET (CTRL+Z), EZT NEM AJÁNLOTT HASZNÁLNI. BEMUTATHATÓ FUNKCIÓK: BÁRMELYIK PIROS (BARÁT) ÉL KITÖRLÉSÉVEL MEGSZŰNIK A BARÁTI KAPCSOLAT A MEGFELELŐ NÉZETIMODELLBELI ELEMEK KÖZÖTT (ÉS PERSZE FORDÍTVA). BÁRMELYIK SZÜLŐ KITÖRLÉSE A CSALÁD "MEGSZŰNÉSÉT" VONJA MAGA UTÁN (TERMÉSZETESEN HA ÚJ CSALÁDOT VESZÜNK FEL AZ IS AUTOMATIKUSAN MEGJELENIK).