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





Authors name (first/last name)

Company

E-mail

Initial

Saadia DHOUIB

CEA LIST

Saadia.dhouib@cea.fr

SD





Revision chart and history log

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







Table of contents

Authors 2

Revision chart and history log 3

Table of contents 4

1 Introduction 5

2 How to install eclipse xtext bundle for papyrus development 6

3 Create and configure your xtext project 9

3.1 Create an xtext project 9

3.2 Configure the xtext project for using UML models 12

4 Build your own grammar 20

5 Create your Xtext pop up editor 22

6 References 23





  1. Introduction

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:







  1. How to install eclipse xtext bundle for papyrus development

  1. 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).

  2. Unzip the distribution eclipse-SDK-3.6M7-xtext-1.0.0M7-win32.zip

  3. 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.




































Figure 1: UML2 installation






































  1. Follow the section III (Papyrus installation in Eclipse Helios) of the tutorial (Eclipse Helios Installation and Configuration for Papyrus Developers), to install Papyrus.

  2. 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 :

    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.

  1. Create and configure your xtext project

    1. Create an xtext project

  1. Use the Xtext wizard to create a new project: File -> New -> Project... -> Xtext -> Xtext project (cf. Figure 2)


Figure 2: Choose Xtext wizard




  1. Choose a meaningful project name, language name and file extension, e.g.

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
































  1. 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.

  1. 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






    1. Configure the xtext project for using UML models

    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:

  1. The first thing we have to do is to add two additional dependencies to the eclipse xtext project (org.eclipse.papyrus.message.editor.xtext) :

To do this, open the file plugin.xml (generated previously) and add the aforementioned dependencies (cf. Figure 6).










Figure 6: Adding plugin dependencies




  1. 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):


Figure 7: Add files to model folder




  1. 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>")





  1. Modify 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”

















Figure 10: Adding a hint for the model generation to EcoreGeneratorFragment




// scoping and exporting API

fragment = scoping.ImportURIScopingFragment {}

fragment = exporting.SimpleNamesFragment {}

// scoping and exporting API

/*fragment = scoping.ImportNamespacesScopingFragment {}

fragment = exporting.QualifiedNamesFragment {} */





















  1. 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:


Figure 13: Editing the extension details




  1. Build your own grammar

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 :

  1. 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.

  2. 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.

  1. Create your Xtext 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:



  1. References

[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 23/23