2016_sirius

Sirius

homesite: http://eclipse.org/sirius/

Install Sirius

Install via update site, which you can find here: https://wiki.eclipse.org/Sirius/Update_Sites On the laboratory we use v6.4.

Setup the laboratory

1. Clone (Xtext branch) and import the following projects from this git repository: https://github.com/FTSRG/mdsd-examples

   hu.bme.mit.mdsd.erdiagram
   hu.bme.mit.mdsd.erdiagram.edit
   hu.bme.mit.mdsd.erdiagram.editor
   

2. Run as Eclipse Application.

3. Switch to Modeling perspective

   Note: Window -> Open perspective -> Other... -> Modeling

▶ Watch the video ▶

Viewpoint specificiation

1. Create a new Viewpoint Specification Project and name it hu.bme.mit.mdsd.erdiagram.design while the Viewpoint specification model would be called erdiagram.odesign. Note: this is a Sirius related project type to describe a Sirius editor

2. In odesign editor, add a new view point: right click on the viewpoint (in the editor) -> New -> Viewpoint. Set its Model File Extension property to "erdiagram".

   

3. Under the viewpoint, create a diagram representation (right click on the viewpoint -> New Representation -> New Diagram Representation) and set its domain class to our root metamodel class: EntityRelationDiagram.

   

4. The default layer is automatically created under the diagram representation. Layers can be switch on and off while using the diagram editor. We will use only the default one.

   

5. In the Metamodels page, add erdiagram.ecore either from registry with nsURI "hu.bme.mit.mdsd.erdiagram" (when the metamodel is installed), or from Workspace by selecting the file (when the metamodel is in the same eclipse instance). In this example, we are developing the views in a runtime eclipse, so select the Add from registry option.

▶ Watch the video ▶

Visualizing objects

Under the default layer:

1. Create a Node diagram element (right click on the layer -> New Diagram Element -> Node) and set its domain class to Entity and its semantic candidates expression to feature:entities. Id can be anything, e.g.: EntityNode we will refer to it later.

   Note: the Semantic Candidate Expression describes the navigation path from the parent domain class to the selected ones. In this the parent is EntityRelationDiagram and we select all the object on its entities reference.

   Note: the feature: selects a structural feature (attribute or reference) from a domain class.

2. Define a style for the Node (right click on the Node -> New Style -> Square). You can change its properties if you want (e.g.: light blue color, disable icon). Also note the label expression is feature:name by default.

   

   ▶ Watch the video ▶

3. Create a Node diagram element and set its domain class to Attribute and set its semantic candidate expression to [entities.attributes->addAll(temporalAttributes)/]. Id can be AttributeNode. Note: inside the square brackets you can Acceleo expressions - Acceleo.

   Note: the EntityRelationDiagram has a temporalAttributes containment reference for attributes not belonging to entities. This will be required later on.

4. Create styles and conditional styles for attributes based on the isKey properties. The condition will be the following: [isKey/]. Right click on the Node -> New Conditional Style -> Conditional Style and then you can create a new style under the conditional style element.

   Note: A default style is always required.

   Note: Do not forget to fill the predicate expression in the conditional style.

   Note: If the predicate expression is true the conditional style will be applied.

   

Try it out

▶ Watch the video ▶

---

1. To try it out, import our example hu.bme.mit.mdsd.erdiagram.examplediagram to the runtime Eclipse.

2. Give the Modeling project nature to the imported project in the context menu -> Configure.

3. In the context menu there will be a Viewpoints Selection item, click it and add the viewpoint specification we have just started to define.

4. Create a new representation as shown on the next figure. Name it as you want and a new editor will open showing the entities and attributes as nodes.

   ▶ Watch the video ▶

Visualizing edges

Display connections between an entity and its attributes

1. Create a Relation Based Edge diagram element (right click on the layer -> New Diagram Element -> Relation Based Edge) with an id EntityAttributeEdge.

2. Set its source mapping to EntityNode (defined previous).

3. Set its target mapping to AttributeNode (defined also previous).

4. Set its target finder expression to feature:attributes or just [attributes/]

   Note: the target finder expression is related to the source mapped objects.

5. By default, a simple edge style is created. Change its decorator (edge ending) to NoDecoration. On the advanced tab set its Folding Style to Source. This will allow to collapse an entity's attributes.

   

▶ Watch the video ▶

Display inheritance relation

Similarly you can define an InheritanceEdge between entities with an isA relation.

▶ Watch the video ▶

Display connections between entities based on the relation objects

1. Create an Element Based Edge diagram element (right click on the layer -> New Diagram Element -> Element Based Edge) and give an id RelationEdge.

2. Set its domain class to Relation

3. Set its source mapping to EntityNode (defined previous)

4. Set its source finder expression to [leftEnding.target/]

5. Set its target mapping to EntityNode (defined also previous)

6. Set its source finder expression to [rightEnding.target/]

7. We left the semantic candidates expression empty, but we should fill it with feature:relations

   Note: for the proper functioning, this is not required but recommended.

   

8. By default, a simple style is provided for the edge, but define additional conditional styles based on the multiplicity of a relation:

   • [leftEnding.multiplicity.toString() = 'One' and rightEnding.multiplicity.toString() = 'Many'/]
   • [leftEnding.multiplicity.toString() = 'Many' and rightEnding.multiplicity.toString() = 'One'/]
   • [leftEnding.multiplicity.toString() = 'Many' and rightEnding.multiplicity.toString() = 'Many'/]

9. Change the ending of the edges based on the multiplicity (inside properties of an edge style, check the decorators tab)

   

▶ Watch the video ▶

At this point we have a fully featured view of our model (except, we can't see the name of the relation endings only the name of the relation:

And we can fold entities, e.g. Person:

▶ Watch the video ▶

Creating Objects

Create a section under the layer, this will represent a section on the Palette of the editor (right click on the layer -> New Tool -> Section)

Create Entities

1. Add a Node Creation (right click on Section -> New Element Creation -> Node Creation).
2. Set the Id field of the Node Creation to Entity, and field to EntityNode.
3. Under the green arrow with the begin label, we can define an operation sequence to be executed.
4. Create a new change context and change the context to the container with the var:container expression.
5. Create a new instance operation (right click on Begin -> New Operation -> Create Instance).
6. Set its reference name to entities. This reference belongs to the EntityRelationDiagram root object, we will add the new entity here.
7. Set its type name to erdiagram.Entity, as we want to create a new Entity.
8. Set its variable name to instance (default).

Note: you can refer to this object later (var:<variable name>).

1. Create a new change context and change the context to the newly created instance with the var:instance expression.

2. Under it, create a Set operation (right click on Create Instance Entity -> New Operation -> Set).

   1. Set its feature name to name.
   2. Set its value to newEntity. This will set the name attribute of the new object.

   

▶ Watch the video ▶

Create Attributes

It goes in the very same way as creating entities. The catch here is the attributes are contained by entities but now we can't connect a newly created attribute immediately to an entity. For this reason, we will use the temporalAttributes containment reference on the EntitiyRelationDiagram element.

After saving, you can add new entities and attributes on the editor.

Note: you can change the display name of the tool with the Label property.

Note: removing and element also works by default by pressing the del button after selecting an element. You can override this behavior by creating a Delete Element under the section.

▶ Watch the video ▶

Creating Edges

Create edge between Entity and Attribute

1. Add a Edge Creation (right click on Section -> New Element Creation -> Edge Creation).

2. Set its edge mapping to EntityAttributeEdge.

   Note: this is the edge element that we defined previous (Visualizing edges/1st step).

3. Set its connection start precondition to [preSource.oclIsTypeOf(Entity)/].

4. Set its connection end precondition to [preTarget.oclIsTypeOf(Attribute)/].

   Note: these two precondition will restrict the editor to disable undesirable edges.

5. Add a Set operation under the Begin element.

   1. Feature name: attributes. (This is related to the source object).
   2. Value expression: var:target. This is a variable created automatically and refers to the selected target object.

   

▶ Watch the video ▶

Create edge between Entities (using Java Code)

1. Add a Edge Creation (right click on Section -> New Element Creation -> Edge Creation)
2. Set its edge mapping to RelationEdge

Note: this is the edge element that we defined previous (Visualizing edges/2nd step).

1. Set its connection start precondition to [preSource.oclIsTypeOf(Entity)/].

2. Set its connection end precondition to [preTarget.oclIsTypeOf(Entity)/].

3. Add an External Java Action operation under the Begin element (right click on the Begin element -> New Extension -> External Java Action)

   1. Set its Id to relationJavaAction.
   2. Set its Java Action Id to hu.bme.mit.mdsd.erdiagram.design.CreateRelationOperation.
   3. Add parameters: source, target (right click on the External Java Action -> New -> External Java Action Parameter)
      • Set their properties:
        • name: source, value source
        • name: target, value target

   

   1. Open the plugin.xml of the project (or the manifest file).
   2. Add hu.bme.mit.mdsd.erdiagram as a dependency in the Dependencies page.
   3. Switch to the extensions tab.
   4. Add a new extension: org.eclipse.sirius.externalJavaAction.
   5. Add a new java action under the extension if it is missing.
   6. Set its id to hu.bme.mit.mdsd.erdiagram.design.CreateRelationOperation (same as Java Action Id!)
   7. Specify an action class: hu.bme.mit.mdsd.erdiagram.design.CreateRelationOperation. Clicking on the "actionClass*:" link will automatically create the class for you. Insert the following code snippet:

public class CreateRelationOperation implements IExternalJavaAction {

	@Override
	public void execute(Collection<? extends EObject> selections, Map<String, Object> parameters) {

		Entity source = (Entity) parameters.get("source");
		Entity target = (Entity) parameters.get("target");

		ErdiagramFactory factory = ErdiagramFactory.eINSTANCE;

		Relation relation = factory.createRelation();
		RelationEnding sourceEnding = factory.createRelationEnding();
		RelationEnding targetEnding = factory.createRelationEnding();
		relation.setName("newRelation");
		relation.setLeftEnding(sourceEnding);
		relation.setRightEnding(targetEnding);
		sourceEnding.setTarget(source);
		targetEnding.setTarget(target);

		EntityRelationDiagram root = (EntityRelationDiagram) source.eContainer();
		root.getRelations().add(relation);
	}

	@Override
	public boolean canExecute(Collection<? extends EObject> selections) {
		for (EObject eObject : selections) {
			if(!(eObject instanceof Entity)) {				
				return false;
			}
		}
		return true;
	}
}

      1. Use CTRL+SHIFT+O to add the missing imports:

import hu.bme.mit.mdsd.erdiagram.Entity;
import hu.bme.mit.mdsd.erdiagram.EntityRelationDiagram;
import hu.bme.mit.mdsd.erdiagram.ErdiagramFactory;
import hu.bme.mit.mdsd.erdiagram.Relation;
import hu.bme.mit.mdsd.erdiagram.RelationEnding;

Note: the added parameters can be reached in the parameters map.

▶ Watch the video ▶

To try it out close the runtime eclipse and import the *.design project from the runtime workspace into the host Eclipse. Then start the runtime Eclipse again. This will install the plugin to the runtime Eclipse and the Relation edge creating should work.

▶ Watch the video ▶

Bonus: Validation

1. Create new validation for our diagram (right click on diagram element -> New Validation -> Validation).

2. Create a new Semantic validation (right click on validation element -> New -> Semantic Validation).

   1. Set its level to Information.
   2. Target class: Attribute.
   3. Message: Unnamed attribute!. This describes what will happen when our model has a problem.
   4. Create an Audit under the semantic validation (right click semantic validation -> new -> audit)
      • Set its audit expression to [name <> 'newAttribute'/]. Note: this describes whether our model is correct or not. If the expression returns false, the element is incorrect.
   5. Create a Quick Fix under the semantic validation (right click semantic validation -> new -> quick fix)
      • Create a Set operation under the Begin element _Note: this is also an operation sequence to be executed when someone click on the quick fix
        • feature: "name", value: "addresss"

   

Now you can validate your diagram by right click -> "Validate diagram". Any newly created attribute should have an "I" mark next to its name. You can use the quick fix by finding this mark in the Problems view, right clicking and Quick fix.

You can find the final state of the projects in this repository by checking out the Sirius branch.

References

• Sirius basic tutorial: https://wiki.eclipse.org/Sirius/Tutorials/StarterTutorial
• Sirius advanced tutorial: https://wiki.eclipse.org/Sirius/Tutorials/AdvancedTutorial
• Sirius full documentation: https://www.eclipse.org/sirius/doc/
• Acceleo language references: AQL OCL Acceleo