h1. Designing Ecore Models

!pasted-images/35ed765cb8af3fb4ab1a95cd3803fe94.png!

h2. Getting Started

Once EcoreTools is installed in your environment, you can start using it either to create a new Ecore model from scratch or to edit an already existing model.

h3. Creating a new Ecore

EcoreTools provide a wizard setting up your Ecore project. Click on __File->New->Others...__ and then select Ecore Modeling Project.

!screenshots/step1.png!

The next page request a project name. The general convention is to use a java namespace notation for your project name. The project which is going to be created actually is an Eclipse plugin project, the name will be used for the plugin identification. 

bq. Changing the project name afterward is possible though error-prone and not without impact. Its better to get it right from the beginning.

!screenshots/step2.png!

The next page request information about your Ecore model. 

bq. Here again, you can keep the default nsURI but keep in mind that its going to be the identifier of your domain within the EMF world. Changing it afterward might requires to update several files.

!screenshots/step3.png!

The next wizard page request which Viewpoints should be enabled. Viewpoints are a way to adapt the tooling regarding your current activity for instance Designing or Reviewing your Ecore model. 
The Viewpoints you might enable are :
* *Design* : when you want to create or adapt an Ecore model. This Viewpoint will enable the __Entities__ diagram to display, create and edit EClasses, EDatatypes and 
EReferences graphically.
* *Review* : for all the tools which are supporting further analysis of your Ecore model. It contributes a new layer on the __Entities__ diagram to display and edit documentation annotations. 
It also provides a table editor to fill the documentation for every model elements and at last but not least it provides a __Dependencies__ diagram you can use to inspect cross EPackage dependencies.
* *Generation* : is available if a __GenModel__ is loaded. It provides a table editor for __GenPackage__ instances to tweak some attributes which are visible in the generated editor : the property category and the end user documentation.
 

If you are really getting started, Design is a good choice, in case of doubt, select everything.

!screenshots/step4.png!

Once you clicked on __Finish__ and the wizard prepared the project, this is what you should have.

!screenshots/step5.png!

h3. Working with the Modeling Project

h4. What is it ?

The *Modeling Project* is a facility provided by Sirius which handles models within the scope of a project. What does that mean ? Any model which is in the project is going to be loaded by Sirius behind the scene and its elements will be available in your editors.

This mode of usage is designed so that you can work with your models easily, but you might want to have more control. In this case, you can use EcoreTools just by creating *Representations Files*.

h4. Selecting Viewpoints

Each modeling project has a set of viewpoints which are _enabled_. This controls what kind of representations you can create on the Ecore models inside the project. 

To select which viewpoints are enabled on your project, simply use the _Viewpoints Selection_ action in the context menu of the project itself.

!pasted-images/6706c17e3282d8ad8953861ac645b081.png!

 A dialog box will open which will show you all the viewpoints which are compatible with your project (depending on the kind of models it contains). You can check or un-check each viewpoint individually to enable or disable it, and click _OK_ to validate your choice.

!pasted-images/d08d23dd487524da5c8ddc2b94c8ca63.png!

h4. Creating a Representation

Once the @Viewpoints@ are selected you can create representations : diagrams or tables. All these representations are stored in the @.aird@ file within the project.

There are several ways to create a representation. You can browse a model in a modeling project and right click on _New Representation_.  

Depending on the type of model element you clicked on, different types or representations might be provided. For instance if you right-click on an @EPackage@ you will have :

!pasted-images/6e7b3308b892cb4fee811e4991ec4b87.png!

And other representations might be created on a @GenPackage@ :

!pasted-images/5f7afbc265b07ed59c8f543d607fffb9.png!

You can also create a new representation by clicking on the @Modeling Project@ itself :

!pasted-images/a0efe2337a4e8f32c1fb429555649174.png!

And then select the kind of representation you want to create. 

!pasted-images/b7e2d60ffc9d0bf815493dba5d538125.png!

In this case the tool will guide you to select a model element for which this representation makes sense. 

!pasted-images/9564b3011878c22b1bd2236ea63e762d.png!

h4. Loading External Models

It is possible to load models which are not in the current project by adding @Project Dependencies@.  You can right click on the @Project Dependencies@ item and add another Ecore file (or type the complete URI)

!pasted-images/02b4636be8ad44ff5e8f0f699eea4e80.png!

h3. Creating diagrams from an existing Ecore

!pasted-images/d357d09ef05edd724b88a10681350182.png!

!pasted-images/3439547e2392f4436fcef49b6bc3543f.png!

!pasted-images/8052cc935a95b635e65a0ed3384ce9b1.png!

!pasted-images/f20119893451c23f3afb1ff3796e51df.png!

!pasted-images/0693d417971137ff01e2864ba838e3c8.png!

!pasted-images/c5f7dabe8549cd2cfc4457ba6512b42b.png!

!pasted-images/004266fe1a19937c4e9d577634d2d6fb.png!

!pasted-images/ef3df56cd674a82d1b09f1e8a5012d15.png!

!pasted-images/55c869b1fa7ba6a813acbcb3e868ebd4.png!

h2. Entities Diagram Editor

The __Entities__ diagram editor has several purpose :
* this is the main tool to create and edit an Ecore model.
* this is the main tool to explore and annotate an existing Ecore model.

This diagram editor is *unsynchronized* meaning it will not automatically display all the __EClasses__ of the current __EPackage__ but only those that you 
explicitely select either by drag&dropping an __EClass__ instance from the *Model Explorer* into the diagram, by using the *Add* tool from the palette or
using the *Add Related Elements* contextual action.

bq. When clicking on *Add Related Elements*  from the background of the diagram, all the __EClasses__ which are contained in the current __EPackage__ will be proposed. This is a convenient way to import
all the __EClasses__ of a given __EPackage__ into a diagram.

References, super types, attributes and operations are automatically imported in the diagram, if you want to remove some of them from a diagram you can either use the 
*Hide* contextual action or leverage one of the filters to hide, for instance, all the *derived references*. 

h3. Overview of the editor

!screenshots/overview.png!

Here is the palette of the __Entities__ diagram editor when both the *Design* and *Review* Viewpoints have been enabled. 

!screenshots/step6.png!

h3. Working with Layers

Several layers are provided by the editor. When activating a layer some shapes and colors will changes and specific tools will be available to address your current concern.
 
!pasted-images/9496bdbf6570c41c40fdc84c34520726.png!

!pasted-images/152133d0d06941c79992c9be5098ecfc.png!

For example, activating the __Documentation__ layer will transform the shape of all the model elements to add a red border if it is not documented. Two new tools are appearing then in the palette so that you can create the doc annotations.  

 
 !pasted-images/590a4be95a110bd5cd35c959dd9ebc76.png!

h3. Navigating in the Diagram

Once your diagram gets populated it might get harder to find a specific EClass. Just like in most of the other Eclipse editors, @CTRL-O@ will summon a small popup which is very convenient to 
find an element. You can select the element in the list and when validating with @ENTER@ the diagram editor will select and reveal this element.

h3. Modeling Classifiers

You can use the tools defined in the palette to create new __EClasses__ or __EDatatypes__ :
* *Class* will create an __EClass__ instance 
* *Abstract Class* will create an __EClass__ instance with @abstract=true@
* *Interface* will create an __EClass__ instance with @interface=true@ and @abstract=true@
* *Datatype* will create an __EDatatype__ instance
* *Enumeration* will create an __EEnum__ instance

Each one of the Class related tools might also be used to change some properties : Using  the tool *Abstract Class* by clicking on an existing __EClass__ will set @abstract=true@, 
Using the tool *Interface* by clicking on an existing __EClass__ will set @interface=true@ and @abstract=true@

bq. This is especially convenient when using the graphical modeler in full-screen with no other view and clicking on the contextual shortcut which appears 
a few milliseconds after you select an __EClass__.

h3. Modeling References

Shortcuts are available in the palette to create different kind of __EReferences__ :
* *Reference* will create a non contained __EReference__ with a @0..*@ cardinality.
* *Bi-directional Reference* will create two __EReference__ instances each one being specified as the @eOpposite@ of the other one.
* *Containment* will create a containment __EReference__ with a @0..*@ cardinality.

You can adapt the __EReference__ properties at any time and the diagram will reflect your changes. If a non-contained reference is changed into a containment reference then the decorator 
at the source of the __EReference__ will be adapted.

h3. Modeling Attributes

Shorcuts are available in the palette to create difference kind of __EStructuralFeatures__, notably:
* *Attribute* will create an __EAttribute__ with a default name when used on an __EClass__.
* *Literal* will create an __EEnumLiteral__ with a default name and valud when used on an __EEnum__.

bq. I the case of __EAttribute__ instances, some typing shortcuts are available. See the "Editing Shortcuts" section.

h3. Modeling Operations

Using the *Operation* tool from the palette and clicking on an __EClass__ in the diagram you can create a new __EOperation__ instance.
To edit the EOperation signature you have several choices, you can directly type it in the diagram, EcoreTools expects a format like :

*name* @(@ param1 : TypeOfParam1, param2 TypeOfParam2 @) :@ *returnType*

You can also directly set the values and create new __EParameter__ instances through the __Properties View__.


h3. Deleting elements

Hitting __DEL__ on the keyboard will delete the selected model element and reset all the cross references to it. If you want to remove an element from 
a given diagram without actually deleting the element, you can either use the @Remove@ tool which is available in the palette or the @Delete from Diagram@ 
contextual action available with a right click.


h3. Validating the model 

If the layer @Validation@ is enabled, then any invalid element will have red borders. To understand what is the error exactly, just keep your mouse pointer above the element and the tooltip will provide you a textual feedback.

!pasted-images/9e62e7e1fca7675f7ad752de2a1d5942.png!


h3. Editing Shortcuts

A lot of shortcuts are available to be more efficient when editing an Ecore model. From a general point of view, just edit the label of a given shape and the diagram editor will try to figure out what you want to edit. For instance:
* typing @1@ on an @EAttribute@ or @EReference@ will switch the cardinality to @1..x@ without updating anything else.
* typing @*@ on an @EAttribute@ or @EReference@ will switch the cardinality to @x..*@
* typing @:SomeTypeName@ will set the type of an @EAttribute@ without updating the name.
* typing @someName@ will update the name, keeping the type and cardinality as-is.
 
Shortcuts appearing contextually to a given @EClass@ will allow you to quickly switch the @EClass@ to being *abstract* or *interface*
 
!pasted-images/971a854713ef86708b9e112a0b7264e7.png!

h3. Exploring Existing Models

EcoreTools provides features which are specifically designed to ease the exploration of an existing Ecore model and assit you in 
creating a diagram to document this exploration.

!pasted-images/08ba8354ba19d7de6c89920fecda9d36.png!

!pasted-images/78b4f8fdbd42aac552d7b092a75cfe70.png!


!pasted-images/ca65ed257a9b2e0433f422811196f8da.png!

!pasted-images/c97a4efe6fbd11a2c40c1046f3684fbb.png!

h3. Setting properties

At any time you have several means to edit the element properties. You can either use the contextual action @Show Properties View@ and then edit from this view or
double-click on an element to open a wizard dedicated to the edition of the properties.

h3. Modeling Generics

You can model EGenerics using the __ETypeParameter__ tool in the palette. When used on an EClass this tool will create a new Type parameter. Once it is created 
you can directly use it in __EOperation__ signatures or even create an EReference targeting this parameter.

!pasted-images/2634caf68113d7bd3b1e85e1df5c4aff.png!

Subclasses will have to specify bounds for this __ETypeParameter__, either by binding to an __ETypeParameter__ of their own or by specifying another EClass.

h3. Modeling Constraints

You can specify domain constraints on an __EClass__. To do so you need to enable the *Constraints* layer. Any constraint which is already defined 
in the model will be automatically imported in the diagram. You can add a new one and bind it to an __EClass__ using the *Constraint* and *Constraint Assignment*
tools available then in the palette.


Constraints are stored in the model using the __EAnnotation__ format supported by the EMF code generation and runtime. The input which is expected when 
you edit a constraint note is a comma separated list of names representing those constraints. For instance : @isWrittenByAnAuthorizedAuthor, isAvailable@

!pasted-images/3f3ad17c7591c30e8a0b1037b7a3a35b.png!

EMF will detect these annotations and generate dedicated Java methods based on this name, you will have to implement them then.

!pasted-images/a4a96011f4f1acbd0331e2a4e258a3bb.png!

h3. Documentation Annotations

!pasted-images/8f3460ca33c1991c8dfdc7caa7152371.png!

h2. Documentation Table Editor

The documentation table displays all the __EPackage__ elements as a hieararchy in the first column and the corresponding documentation annotation in the second one.

To edit an existing annotation or to create a new one, select the corresponding cell and type using the keyboard.

!images/documentation_table.png!


h3. Dependencies Diagram Editor

A *Depdencies* diagram can be created from en __EPackage__ when the *Review* viewpoint is enabled for your project.

This diagram is helpfull to visualize and analyze the direct dependencies between two __EPackage__.

To leverage it, use the *Add...* tool from the palette to import the __EPackage__ instances you want to inspect. These instances will be displayed as list containers.
If any dependency exist between two __EPackages__ then an edge appears in the diagram. Within the __EPackage__ representation list the __EClasses__ instances which 
are involved in this dependency will automatically be displayed by the tool.

!pasted-images/ae061e611b11578818a2e2a2c4c847d8.png!

Hovering your mouse over such an __EClass__ to have an explanation of the dependency.

h1. Leveraging Ecore Model

EcoreTools directly edits the Ecore model in a standard way, no special operation is required to leverage the model itself.
You can open a __GenModel__ instance and launch the EMF code generation for instance.

A specific tool in the palette named *Dynamic Instance* allows you to quickly create an instance of your domain model without requiring any code generation.
To use it select the tool *Dynamic Instance* and apply it on the __EClass__ of your choice in your diagram. A wizard will be opened to guide you through the process of 
creating this XMI file, once the file is created the *EMF Reflective Editor* will be opened to edit it.

 
h1. Exporting Diagrams

You can export an existing diagram in several format by right-clicking on the diagram itself.
You can also export all the representations stored in a @.aird@ file by right-clicking on the file in the *Explorer* and selecting @Export as images...@.

h1. FAQ

h2. What should I do with my .ecorediag diagrams ?

Indeed from version 2.0 EcoreTools moved from GMF Tool to Sirius as a backend technology and that meant adopting the .aird file format for diagrams and other representations.

Writing a migration tool from .ecorediag to .aird is possible though we've seen that in practice if you have a .ecorediag opened and want to reproduce the corresponding diagram using Sirius 2.0, you can do so quite quickly.

bq. As I said, this is technically doable so if you have hundreds of diagrams and want a financial quote related to this work feel free to ask.

To ease the transition both implementations have been provided with EcoreTools 2.0 but only the Sirius based one has been aggregated in the Eclipse Luna update-site. You can install the legacy editor which supports the .ecorediag format using the "EcoreTools update site":http://www.eclipse.org/ecoretools/downloads .
   
 
h2. This marker is bothering me in the diagram, how can I remove it ?

You can remove the validation marker by using the "Problems" view, select the error which bothers you, right-click, and delete. It will disappear from the diagram then.

h2. My diagram is getting big, how to find an element ?

To quickly find something in a diagram just type @CTRL+O@, type a partial name and select it. The editor will reveal it for you.


h1. Getting Help

You can interact with the team behind *EcoreTools* by using the "Eclipse Forum":http://www.eclipse.org/forums/index.php/f/165/ 
