Specifying Viewpoints

  1. Specifying Viewpoints
    1. Introduction
    2. Philosophy and Concepts
    3. Viewpoint Specification Projects
    4. Viewpoint Specification Models
      1. Organization
      2. Common attributes
      3. Type Names
      4. Interpreted Expressions
      5. Feature Name
      6. Translatable Messages
      7. Model Operations
      8. Quick Outline
      9. VSM Validation
      10. Dynamic Development
      11. Migration from Previous Versions


TODO Add a few screenshots to make the document less dry.

This document gives a general overview of how viewpoints are specified, tested and deployed.

Introduction

Sirius is a modeling tool which has been originally created in the context of complex systems modeling. The complexity of those systems makes necessary the collaboration of people with different concerns. For the same domain and on the same data, there are different levels of analysis, different roles and different concerns possible. Each of these correspond to a different viewpoint on the same domain model, and Sirius (the system) gives you all the tools to specify the viewpoints which are relevant to your business domain, whatever it is.

More pragmatically, Sirius assumes that you domain model is defined using EMF (Eclipse Modeling Framework), which is an industry standard with a rich eco-system. Many existing standards like UML (for software systems) or TOGAF (for Enterprise Architecture) have an implementation based on EMF. You can also easily define your own Domain-Specific Model (sometimes called Domain-Specific Language) to more precisely suit your specific needs and avoid unnecessary complexities. While this part (the domain specification) is not strictly in the scope of Sirius, the system provides a graphical modeler to ease the creation of your own DSM (Domain-Specific Model).

Given such a domain model, which defines concepts and their relations in the abstract, Sirius will allow you to easily specify concrete representations of these models. Representations can be diagrams, tables, matrices (cross-tables) or hierarchies (trees). You can define as many of them as you need, some more detailed than others, some customized for certain tasks or roles (e.g. initial design, review, certification, etc.). These representations are not just static: provided you specify the appropriate tools (see below), they can be complete modeling environments where users can create, modify and validate their designs. Representations can be logically organized in viewpoints, and end-users can enable or disable viewpoints at will to work on the same model through different, but logically consistent, points of view.

The main strengths of the Sirius platform can be summarized as is:

Philosophy and Concepts

As explained in introduction, Sirius allows you to specify dedicated representations and associated tooling. As a specifier, your role will be to configure the generic Sirius platform to provide these representations to your users. This is done by creating and configuring a Viewpoint Specification Model which describes the structure, appearance and behavior of your modelers. This document does not deal with the definition of your domain model; you can use a standard one like UML, SysML, BPMN or TOGAF, or create a custom one. The only assumptions Sirius makes is that your model is based on EMF.

The main concepts you will work with as a specifier are:

Viewpoint Specification Projects

Note: When working as a Sirius specifier, it is recommended to use the Sirius perspective, which provides some additional shortcuts and views. The Modeling perspective is simpler and oriented towards end-users.

Viewpoints are specified as models (see below) inside Viewpoint Specification Projects. These VSPs are normal Eclipse plug-in project, which happen to contain one or several *.odesign files (the extension used for Viewpoint Specification Models ). You can create such a project using the supplied wizard: New > Viewpoint Specification Project.

By convention, the VSM (or VSMs) defined in your project are stored inside a description folder. If you want to place them in a different location, make sure to add this location into the plug-in’s build.properties so that it is included in the deployed version.

The VSM name is given according to the project name defined when using the previous wizard. If the project name is suffixed with “design”, the VSM name is provided by the last word before this suffix. Otherwise, the VSM name is given by the last word of the project name.

Other than that, the project is a normal Java plug-in project. You can add service classes into it if the query language you use support it, and any other Java code, including Eclipse views, actions, etc.

Note that it is recommended to add your domain meta-model(s) plug-ins as dependencies of the project. Java services and some features of query language (like the use of type literals in AQL filter() operations) might require them.

Important: Any VSM you place in the Eclipse workspace will be immediately available for use and testing, with no deployment. This is to facilitate dynamic and iterative development of viewpoints. However, when you deploy your VSMs, they must be part of a VSP, and they must be registered in the plug-in’s activator class. The activator generated by the VSP wizard is properly configured, but if you rename your VSM or add new ones, be sure to edit the activator class so that all your VSMs are correctly registered inside the Sirius platform when deployed.

Viewpoint Specification Models

The core part of a VSP is the Viewpoint Specification Model (or models) it contains. These are stored in *.odesign files, usually in the description folder of the project. A VSM specifies a set of Viewpoints and their representations (diagrams, trees...).

To edit a VSM, simply double-click on it, and a tree editor will open. The editor follows the conventions of standard EMF editors: selecting an element will show its properties in the Properties view, where you can edit them. To create new elements, simply right-click on its parent and choose from one one the New XXX menus. To delete an element and all its sub-elements, simply select it and hit the Delete key or right-click and choose Delete.

Organization

The top-level element of a VSM is a Group element. It has no specific semantics and serves only as a container for the other elements. Note however that once you define its Name, you should never change it as it becomes part of the identification of all the elements inside the VSM. If you change it, any concrete representations created using that VSM will be broken.

Inside a Group, you can create an optional User Colors Palette, with shared color definitions; this is useful to define a uniform color palette for all your viewpoints and representations. You can also, and more importantly, define Viewpoint elements.

Besides its Id and Label (see below), a Viewpoint can be associated to one or more Model File Extensions, separated by space. This can be used to restrict the availability of the viewpoint only to modeling projects which contain semantic models of the specified types. For example, to make your viewpoint available to UML and SysML models, you can specify uml sysml (note that the syntax specifies only the file extension, uml, not a pattern like *.uml). You can use a star, *, to make your viewpoint available for all models, but it is normally prefered be as specific as possible so as not to interfere with unrelated models and projects.

Inside a Viewpoint element, you can create:

To discover all elements in the VSM, it is possible to use the button , at the top right corner of the editor to expand the VSM tree. Obviously, it is possible to collapse this tree by using the button , at the top right corner of the editor.

Common attributes

Many of the elements used to specify viewpoint share some common configuration attributes. They are described in general terms in this section, and referenced from the specific element’s sections which used them (sometimes with additional details only relevant for this element).

use the icon to access the available fields tooltips.

Type Names

Some VSM elements will need you to specify one or more Type Names to configure them, usually types from the semantic domain model being represented (for example the Domain Class for mapping definitions). You can easily identify Type Name fields by their green background in the Properties sheet of an element.


The syntax for type names are the following:

Auto-completion is available in these fields using the Ctrl+Space shortcut. It is recommended to explicitly associate a meta-model (or more) to your representations definitions to allow for smarter completion. Otherwise by default it will include all types from any EMF meta-model available.

Interpreted Expressions

Many VSM elements require you to specify Interpreted Expressions to configure them. These can be queries to select elements (as in mappings for example), or more general expressions to compute value (like the text to use for the elements' labels).

You can easily identify Interpreted Expressions by their yellow background in the Properties sheet of an element. For all such field, you can use any of the supported languages to write the expression. Refer to the queries documentation for more details.

Also, by clicking on the button next to the text field, you can open a dialog with a bigger text area (providing auto-completion too) to type your expression more comfortably. Note that you can add line feeds or tabulations if you want, since they are removed when clicking on the “OK” button.

Feature Name

Some VSM elements will need you to specify a Feature Name (or Reference Name on Create Instance) to configure them (Create Instance, Set, Unset, etc.). You can easily identify Feature Name fields by their light green background in the Properties sheet of an element.

Auto-completion is available in these fields using the Ctrl+Space shortcut except if the current element type cannot be inferred, usually in the case of a generic tool where the target element will be known only at runtime.
Note that for Create Instance Reference Name field, the completion will display only features that have a type consistent with the one specified in the Type Name field. If no type is specified, all available features will be displayed. In the same way, if a valid Reference Name is set, the completion for the Type Name field will display only types consistent with the feature type.

Translatable Messages

Many VSM elements provide text fields that will be displayed when end-users reference the VSM in a modeling project (Viewpoint name, tools...). Starting from Sirius 4.0, the value shown to the end users can be localized according to the user’s language. Fields which support this feature are called Translatable Messages and can be easily identified by their blue background in the Properties sheet of an element.

Note that on the previous screenshot, the text in the label field is grayish because no label have been set and the ID is used instead.

This feature is available for almost every VSM elements defined in the VSMs which are visible to the end-user of the modeler, like viewpoint and tools names, can now be internationalized, but not to interpreted expressions. Note also that this feature is only available to modelers which are deployed as proper Eclipse plug-ins; it will not work for plain VSMs defined directly in the runtime workspace.

To make use of this feature in your modeler, simply replace the names with a translation key reference of the form %myUniqueKey in the VSM, and define the value in the Viewpoint Specification Project's plugin.properties (for the default value), or plugin_XX.properties for locale XX. Note that the key chosen must be globally unique in the context of a whole Viewpoint Specification Project.

The key must be added to the plugin.properties file for each language with the translated message. The default properties file is named plugin.properties and the localized version are identified with a postfixed with the corresponding language code (e.g. for US english plugin_en_US.properties, for french plugin_fr.properties). The underlying mechanism is the same as for Eclipse/OSGi plug-ins, so translations can even be contributed by physically separate plug-in fragments. For the message values to be found at runtime, do not forget to:

An Eclipse with localization in english will get the localized messages from plugin_en.properties, while an Eclipse with localization in french will get the localized messages from plugin_fr.properties.

English locale French locale (with corresponding translation in plugin_fr.properties

Note that an Eclipse with localization in a language that has no dedicated properties file, will get the localized message from the default plugin.properties.

If the ID is not found in the localized properties file or if there is no properties file, the ID will be directly displayed.

As the internationalization is optional, if a Translatable Message does not start with a % it will be directly displayed without consideration of the localization.

It is still possible to display a non localized label starting with a % however the character needs to be doubled.


Warning: Translatable Messages concern only labels set in the VSM that are displayed to the end-users. Sirius is prepared for internationalization but is only available in English. Therefore, the VSM labels can be available in another language but the labels coming from Sirius will stay in English. Moreover, some labels come from some other frameworks (such as EMF or GMF) and if the localization feature (if existing) is not installed, then the labels will stay in English.

Model Operations

Whenever a VSM requires you to specify a behavior, for example inside any Tool definition, you can use any of the available Model Operations to do so. Refer to the Model Operations documentation for more details.

Quick Outline

When defining your VSM, a quick outline is available with the shortcut Ctrl + O. This allows you to rapidly search text in the displayed name or the contained String attributes of your VSM elements.

The star, *, is a joker character, allowing you to search with more complicated patterns. Regarding this, an element is found if there is a word in its name or one of its attributes that match with the text in the filter, so if you want to search within words too, add * at the start of your pattern. Also, you can navigate along the matching elements with and , and go to the selected element in your VSM with Enter.

VSM Validation

It is possible to validate your Viewpoint Specification Model , to check that your Representations, Mappings and Tools are correctly specified. It will help you to find missing element or erroneous one (e.g. missing required expression).

To validate your VSM, open your odesign file, right-click on the top-level Group element and select Viewpoint specification Editor > Validate. A dialog Box will appear and indicate if the validation succeeded. If not, it will give you details about the detected problems (click on the ‘details’ button of the dialog box). If problems are detected, they will also be added to the Eclipse Problems view. Double-clicking on one of these problems will select the concerned element in the Viewpoint Specification Model editor.

You can also validate one specific element by right-clicking on it in the Viewpoint Specification Models and launching the validation process. All the children of the selected element will be validated too. This fine-grained validation is useful to localize issues in the Specification Model, especially when it contains a lot of elements.

It is also possible to use the button , at the top right corner of the editor to launch the validation. This icon changes () when we change the VSM to encourage the user to validate the VSM before saving.

Dynamic Development

Sirius supports dynamic development of your VSM with no need for deployment of your project to test it. If the domain model definition (the EMF meta-model plug-in) is installed in your development environment, and as long as your VSM does not use advanced features which require a deployment (like the definition of new External Java Actions for example), you can test your representations while you are developing them. It is the recommended way to work, especially in the initial development phases, to easily experiment different approaches and see the results immediately.

To do this, simply create a modeling project in your development environment, alongside the Viewpoint Specification Project, and add a sample domain model to it. When you open the Viewpoints Selection dialog on the sample project, you will see that all the viewpoints which are being developed in the same workspace are also made available, in addition to the ones installed as plug-ins. Select the ones you want and create sample representations.

Keep both your representations and the VSM that define them open at the same time. Whenever you change some definition or add new elements into your VSM, simply save it. Sirius will automatically detect the change, reload the new definition and apply it to your existing representations. This way you can develop your representations iteratively, for example starting from an empty diagram and adding more elements, styles and tools while and testing them immediately.


TODO Add a screenshot with both a VSM (on the left) and the corresponding diagram (on the right) opened at the same time. Make sure the “Model Explorer” is also visible to show both the VSP and the Modeling project they correspond to.

Note that Sirius does its best to take into account any change in the VSM, even for existing and opened representations. Sometimes, if the changes are too complex or in some corner cases not yet supported, you may need to close and reopen your representation, or in extreme case delete it and create a new one, in order to take the VSM changes into account properly.

Reload installed VSM

Even though having your VSP in the runtime environment workspace is the best way to do dynamic development of your VSM, if your VSP is in the installed runtime plug-ins (that is the VSP plug-in is in the development environment workspace), you have the ability the reload it from your runtime to take external changes into account.
This is done with the Reload installed VSM action from the main Eclipse tool bar.
Click on Reload installed VSM will have automatically effects in opened representations(depending on refresh options).

Limitations:

Migration from Previous Versions

The Viewpoint Specification Model can evolve between two versions of Sirius. The migration process is done automatically. That means all VSM are migrated at loading time without any action from the user. While a VSM is not saved, the automatic migration will be replayed at the next opening.