Tutorial
on embedding Xtext editors inside Papyrus diagrams Version 0.2
|
Papyrus Tutorial:
How to embed an xtext editor inside a papyrus diagram
Editor |
Saadia DHOUIB, CEA LIST |
Status |
Production |
Version number |
0.2 |
Date of preparation |
2010-05-18 |
Authors name (first/last name) |
Company |
|
Initial |
Saadia DHOUIB |
CEA LIST |
SD |
Version |
Date |
Reasons |
0.1 |
18/05/10 |
Initial contribution. |
0.2 |
03/06/10 |
Sections 1, 2, 3 finished |
0.3 |
04/06/10 |
Section 4, 5 finished |
|
|
|
|
|
|
Authors 2
Revision chart and history log 3
Table of contents 4
2 How to install eclipse xtext bundle for papyrus development 6
3 Create and configure your xtext project 9
3.2 Configure the xtext project for using UML models 12
Xtext is a framework for the development of domain-specific languages and other textual programming languages. It is tightly integrated with the Eclipse Modeling Framework (EMF) and leverages the Eclipse Platform in order to provide a language-specific integrated development environment (IDE).
The purpose of this document is to provide a tutorial for Papyrus users and developers, explaining the followings:
how to install and configure the xtext eclipse bundle for papyrus development
how to create and configure an xtext project
how to build an xtext grammar
how to develop an xtext editor integrated in a papyrus UML diagram
Download the Xtext distribution which is based on the Eclipse Helios M7 release from http://xtext.itemis.com/xtext/language=en/23947/downloads. This tutorial will be based on Eclipse 3.6M7 (Helios) + TMF Xtext 1.0.0M7 distribution, which contains TMF Xtext 1.0.0M7, M2T Xpand 1.0.0M7, MWE 1.0.0M7, MWE2 1.0.0M7, EMF Compare 1.1M7 and Subversive 0.7.8 (incl. SVN-Connectors).
Unzip the distribution eclipse-SDK-3.6M7-xtext-1.0.0M7-win32.zip
To be able to develop papyrus
diagrams with this eclipse version, one have to follow the tutorial
(Eclipse
Helios Installation and Configuration for Papyrus Developers).
Install the
packages that are missing following the steps detailed in section I
(Eclipse
Helios Installation). It is important to download the latest version
of the packages listed below.
Ignore steps 1 and 2
Install the emf-query-update plugin following step 3
install the emf-validation plugin following step 4
install the m2m-qvttom plugin following step 5
install the GEF-update plugin following step 6
install the gmf-gmf-Update plugin following step 7
install the emf-eef-Update plugin following step 8
install the mdt-uml2-Update plugin. Select only the elements indicated in Figure 1.
Figure
1: UML2 installation
Follow the section III (Papyrus installation in Eclipse Helios) of the tutorial (Eclipse Helios Installation and Configuration for Papyrus Developers), to install Papyrus.
Follow the section IV of the tutorial (Eclipse Helios Installation and Configuration for Papyrus Developers), to configure Eclipse for Papyrus development.
In addition to the configuration steps specified in the aforementioned tutorial, you have to do some other configurations. Some projects have unsatisfied dependency to org.eclipse.uml2.uml.edit. To resolve this dependency, you have to download two plugins from a CVS repository.
Go to the Menu 'Window->Open Perspective->Others…->CVS Repositories'. Right click on the CVS Repository Tab, then 'New->Repository Location'. Complete the fields with the following values and click on Finish.
host : dev.eclipse.org
repository : /cvsroot/modeling
In the CVS Repository, go to /HEAD/ org.eclipse.mdt/org.eclipse.uml2 :
Select org.eclipse.uml2.common.edit, Right click and check out.
Select org.eclipse.uml2.uml.edit, Right click and check out.
Some other projects have unsatisfied dependency to org.eclipse.ocl.uml. In the same CVS Repository, go to /HEAD/ org.eclipse.mdt/org.eclipse.ocl/plugins. Select org.eclipse.ocl.uml, Right click and check out.
Use the Xtext wizard to create a new project: File -> New -> Project... -> Xtext -> Xtext project (cf. Figure 2)
Figure
2: Choose Xtext wizard
Main project name: |
org.eclipse.papyrus.message.editor.xtext |
Language name: |
org.eclipse.papyrus.message.editor.xtext.UmlMessage |
DSL-File extension: |
umlmessage |
Keep “Create generator project” checked, as we will also create a code generator in a second step (cf. Figure 3). Click on Finish to create the projects.
Figure
3: Create new xtext project
Project Layout:
In the Package Explorer you can see
three new projects (cf. Figure 4). In
org.eclipse.papyrus.message.editor.xtext
you can define
the grammar and configure the runtime aspects of your language. The
editor, outline view and code completion goes into
org.eclipse.papyrus.message.editor.xtext.ui
. Both
projects consist of generated classes derived from your grammar and
manual code such as the grammar itself or further classes to
differentiate from the default behavior.
Figure
4: Xtext project layout
It is good to be clear and unambiguous whether the code is generated or is to be manipulated by the developer. Thus, the generated code should be held separately from the manual code. We follow this pattern by having a folder src/ and a folder src-gen/ in each project. Keep in mind not to make changes in the src-gen/ folder. They will be overwritten by the generator.
Build the generated sample
grammar: The wizard will automatically open the example grammar file
UmlMessage.xtext
from the first project in the editor.
We will test the generation of the language artifacts. To do this,
locate the file GenerateUmlMessage.mwe next to the grammar file in
the package explorer view (cf. Figure 5). From its context menu,
choose Run As -> MWE Workflow. That will trigger the
Xtext language generator. You will see its logging messages in the
Console view. No errors should appear in the Console view. The
purpose of this step is to obtain the file plugin.xml that will be
modified in the next step.
Figure
5: Generate language artifacts
Papyrus projects are based on UML2 models. To combine the xtext defined grammar with the existing UML2 model, it is necessary to do the following steps:
The first thing we have to do is to add two additional dependencies to the eclipse xtext project (org.eclipse.papyrus.message.editor.xtext) :
org.eclipse.uml2.codegen.ecore (1.0.6)
org.eclipse.uml2.uml (3.1.0)
To do this, open the file plugin.xml (generated previously) and add the aforementioned dependencies (cf. Figure 6).
Figure
6: Adding plugin dependencies
The models are integrated in the eclipse environment. For a standalone usage they have to be copied to the xtext project. Add a new folder “model” and add the following model files to it (cf. Figure 7):
UML.genmodel
UML.ecore
Ecore.ecore
Ecore.genmodel
Figure
7: Add files to model folder
The grammar must gain knowledge about the UML2 model. This can be done with the following import in the UmlMessage.xtext grammar file:
import "http://www.eclipse.org/uml2/3.0.0/UML" as uml
Figure 8 illustrates this import.
Figure
8: import UML2 metamodel in the xtext grammar file
With the alias uml the UML2 model elements can be used in the grammar, such as shown below:
NameRule: name=ID
':'
((type=[uml::Classifier])
| "<Undefined>")
Modify the GenerateUmlMessage.mwe2 file:
The packages “UMLPackage” and “GenModelPackage” have to be setup. This allows the generator to resolve the uris. The original uri references point to the plugins environment, so a uri mapping helps the generator. You have to add the following code in the GenerateUmlMessage.mwe2 file:
bean
= StandaloneSetup { platformUri
= "${runtimeProject}/.." registerGeneratedEPackage
= "org.eclipse.uml2.uml.UMLPackage" registerGeneratedEPackage
= "org.eclipse.uml2.codegen.ecore.genmodel.GenModelPackage" uriMap
= {from="platform:/plugin/org.eclipse.emf.ecore/model/Ecore.ecore"
to="platform:/resource/org.eclipse.papyrus.message.editor.xtext/model/Ecore.ecore"} uriMap
=
{from="platform:/plugin/org.eclipse.emf.ecore/model/Ecore.genmodel"
to="platform:/resource/org.eclipse.papyrus.message.editor.xtext/model/Ecore.genmodel"} }
Figure 9 shows the exact place where this code has to be added.
Figure
9: Modify the mwe2 file to setup “UMLPackage” and
“GenModelPackage”
The next step in the workflow, you have to add a hint for the model generation to EcoreGeneratorFragment fragment (Figure 10). So the generator can use the UML2 API.
Figure
10: Adding a hint for the model generation to EcoreGeneratorFragment
Finally you have to change the scoping and exporting part in the mwe2 file, following the code below:
//
scoping and exporting API fragment
= scoping.ImportURIScopingFragment {} fragment
= exporting.SimpleNamesFragment {} //
scoping and exporting API
/*fragment
= scoping.ImportNamespacesScopingFragment {} fragment
= exporting.QualifiedNamesFragment {} */
The org.eclipse.papyrus.message.editor.xtext.ui plugin has to extend a papyrus extension point which is org.eclipse.papyrus.extensionpoints.editors.DirectEditor . To do this you have to follow the steps below:
Select plugin.xml in the org.eclipse.papyrus.message.editor.xtext.ui project. Go to Dependencies corner, and add a dependency to org.eclipse.papyrus.extensionpoints.editors, as shown in Figure 11.
Figure
11: Adding dependency to
org.eclipse.papyrus.extensionpoints.editors
Go to Extensions corner, and add a new extension which is org.eclipse.papyrus.extensionpoints.editors.DirectEditor (cf. Figure 12).
Figure
12: Add new extension
Edit this extension by: (cf. Figure 13)
Setting the language to Advanced message editor,
Setting the objectToEdit to org.eclipse.uml2.uml.Message. Indeed in this tutorial we will create an xtext editor that will edit the name of a UML message in a papyrus UML communication digram.
Setting the contributer to CEA List.
Figure
13: Editing the extension details
Select the previously created extension org.eclipse.uml2.uml.Message (DirectEditor), right click on and choose “New popup editor”. In the extension Element Details corner, select 'editor configuration', and set the name of the package and the class as shown in Figure 14. Before that, you are supposed to create the package org.eclipse.papyrus.message.editor.xtext.ui.contributions in the src folder of the project org.eclipse.papyrus.message.editor.xtext.ui .
Figure
14: Set the editor configuration
Many tutorials on the web can help you to create your grammar [1, 2].
Important note: (I'm not sure of what I'm saying here, Arnaud please verify this) Avoid using terminal rules because they may hide each other!! Use data type rules or Parser rules. In the example below, we show the grammar of the UMLMessage label.
grammar
org.eclipse.papyrus.message.editor.xtext.UmlMessage with
org.eclipse.xtext.common.Terminals
import
"http://www.eclipse.org/uml2/3.0.0/UML"
as
uml generate
umlMessage
"http://www.eclipse.org/papyrus/message/editor/xtext/UmlMessage" MessageRule:
sequenceTerm
+= SequenceTermRule
('.'
sequenceTerm += SequenceTermRule)* ':' name
= nameRule ; SequenceTermRule
: sequencialOrder
= INT //represents the sequential order
of the Message within the next higher level of procedural calling (sequenceName
= ID)? // represents a concurrent
thread of control. Messages that differ in the final name are
concurrent at that level of nesting (recurrence
= RecurrenceRule)? // The recurrence
represents conditional or iterative execution. ; terminal
nameRule: ('a'..'z'|'A'..'Z')
('a'..'z'|'A'..'Z'|'_'|'-'|'0'..'9')*; RecurrenceRule
:
('*'
'['
STRING ']')|('['
STRING ']')
;
Once you have created your grammar, you can :
generate language artifacts: Save the grammar and make sure that no error markers appear. Then, locate the file GenerateUMLMessage.mwe next to the grammar file in the package explorer view. From its context menu, choose Run As -> MWE Workflow. That will trigger the Xtext language generator. You will see its logging messages in the Console view.
Run the generated editor: If code generation succeeded, right-click on the Xtext project and choose Run As -> Eclipse Application. This will spawn a new Eclipse workbench with your projects as plug-ins installed. In the new workbench, create a new project ( File -> New -> Project... -> General -> Project) and therein a new file with the file extension you chose in the beginning. This will open the generated entity editor.
Once you have created and tested your grammar, you can go to the next step which is embedding the XtextEditor inside a pop up Editor.
Here I have to explain the class MessagePopupEditorConfigurationContribution, specially the
createPopupEditorHelper method and getTextToEdit method.
In section 3.2, we have explained how to extend the papyrus extension point org.eclipse.papyrus.extensionpoints.editors.DirectEditor.
The created class MessagePopupEditorConfigurationContribution, have to extend org.eclipse.xtext.gmf.glue.PopupEditorConfiguration class.
The latter class is provided in the org.eclipse.xtext.gmf.glue project. You have to import this project from the SVN repository : (Here add the svn path)
The two method that you have to customize inside the MessagePopupEditorConfigurationContribution class are:
getTextToEdit: this method returns the string that will be edited inside the popup editor.
createPopupEditorHelper: this method is responsible for displaying the Xtext popup editor...
[1] Xtext tutorial, http://www.eclipse.org/Xtext/documentation/latest/xtext.html#getting-started
[2] Xtext Reference document, http://www.eclipse.org/Xtext/documentation/0_7_2/xtext.pdf,2009
2010 The
Papyrus Consortium