Revision as of 12:12, 27 February 2015

Enhancement of the support for the stereotypes in Papyrus

This page presents the improvments that will be pushed in the Mars version of Papyrus regarding the stereotypes support in the tool.

Introduction

The starting point of this study is due to concomitant issues around the stereotype display:

• The first whished improvement is to display the stereotypes when dragged and dropped from the model explorer.
• The second whish would be to use the Named Styles instead of EAnnotation in order to be aligned with the Papyrus point of view and be based on GMF layer.
• The third point is the user interface to display the Stereotype that doesn’t fulfil the user expectation in terms of intuitiveness.

State of art

Concepts in place

The Stereotype feature contains two types of display, which are more or less independent.

• The stereotype name label
  • Can be displayed or hidden
  • With a short name or a Qualified Name
• The stereotype properties
  • Can be displayed or hidden
  • Can be shown in a compartment, as a comment or in braces

On top of that, there are several actions taking part in the stereotype display:

• When displaying or hiding an item (stereotype Label or property label) from the appearance property view.
• When a new stereotype is applied or unapplied from the profile tab into the property view.

Those different cases should be part of the solution. But as there are quite independent, they can be treated as such.

Conception

In Papyrus, Stereotypes are stored into UML model. But the information related to the manner to display stereotypes is stored through the EAnnotation. EAnnotation is an EMF concept that is attached to an object of type EModelElement. The EAnnotation details is a Map of type EMap<String,String>. In the case of “Stereotype”, the EAnnotation name is “Stereotype_Annotation”, the related map contains the following list of properties and values:

Property View

The profile and stereotypes applied are available under the tab “Profile” of the property view of the diagram or of the object. All the information about the display of those stereotypes is available under the “Appearance” tab.

1. What information should be displayed (Text, icon, image, text and Icon)
2. How the stereotypes should be aligned (Horizontal or vertical )
3. Location of the stereotype information to be displayed (in a specific compartment, as a comment, or between bracket )
4. The selection tree of the applied stereotypes with their properties
5. Pair of buttons to display either short stereotype name, or the whole qualified name.

Architecture

Here is the general overview of the Stereotypes architecture with EAnnotation.

Here is the class diagram of the Stereotype EAnnotation concept:

Observations

Several observations can be done from this conception:

1. EAnnotation is difficult to maintain, it is string based only, and a lot of classes, constants and methods are required to put EAnnotation in place.
2. EAnnotation is not well designed for a CSS compatibility. It is then difficult to have a good customization.
3. The user interface into the “Appearance” Tab is not clear. The two buttons to display qualified name and short name are ambiguous.
4. The property view is directly in charge of creating Commands to manage the EAnnotation, instead of separated responsibilities between graphical interface, user actions, and command creations.

For those reasons, the entire Stereotype display mechanism must be improved.

Requirements ( Draft )

Solutions

Different solutions have been studied to find the best soution. First suggestion is to translate all the Eannotation properties into NamedStyle properties. Second soltution would be to define one label by stereotype. This chapter will describe the different solutions.

Named Styles

Based on the previous analysis, the Named Styles seems to be a good approach. This chapter explains how Named Styles work and how it can be integrated into the code to display stereotypes. Named Style is a GMF concept based on the Notation file. Named Styles define typed properties as a Style into the notation file. Types for Named Styles are the primitive ones: int, boolean, string, list, double… Notation file can be overridden by the CSS that is also accessible by the Named Style.

Architecture

Here is the general overview of the new solution for the Stereotypes to be displayed with Named Styles.
Note: method’s name is informative and not definitive. The direct edition of the stereotypes from the appearance property view is now done through the Edit Part which centralizes the different actions to be executed to display, hide, and update the stereotypes to be displayed.

CSS and Named Styles

In order to keep as many liberty degrees to the user as for the present solution, the same set of parameters is required. To allow the user to define the list of Stereotypes to hide from CSS and from the user interface, different list should be used for the CSS and the notation file. Then the lists can be merged instead of being overriden.

Those means that a lot of lists should be implemented as a parameter:

• stereotypesToHide
• stereotypesToDisplayAsQN
• stereotypePropertiesToHide
• stereotypesToDisplay
• CSSStereotypesToHide
• CSSStereotypesToDisplayAsQN
• CSSStereotypePropertiesToHide

Pro & Cons

The advantage of this solution is that the mechanism is quite close from the initial one. The CSS can be used as a user preference. It is based on GMF as required. And the intelligent part is done by a controller instead of via the interface directly.

In a other hand, this solution won't work if there are several CSS files used at the same level ( for example for each stereotype) . By default, the CSS mechanism will choose the CSS file with higest priority and ignore the other ones. On top of this, the list management between CSS and Notation file would be difficult to maintain and is a source of troubles.

Label for Each Stereotype

Another solution would be to change the architecture and specify one label for each stereotype. The difficulty here would be that the list of stereotypes that can be applied is not exhaustive. So it is not possible to create an UML object for each type of stereotype. The solution would be then, to create the label directly when the stereotype is applied. This solution avoid the use of lists and with the parameter "isVisible" can be shown or hidden from the CSS file without duplicating properties.

Architecture

The Architecture is quite similar to the NamedStyle solution, except the new Label element with the following properties:

• Type
• Stereotype
• isVisible
• QNDepth
• Properties

CSS and NamedStyles

NamedStyles will also be used in this solution for the properties that are not designed by default (like the QNDepth) and required into the CSS. The stereotypes would be shown or hidden through the CSS thanks to the following command:

Label[type=StereotypeLabel][name="SysML::Blocks::Block"]{
   isVisible : false;
   depth: "full";
}

Pros & Cons

• Pros : Using one label for each stereotype allows several CSS at the same level. The solution avoids lists of String management. Simple to maintain.
• Cons: The stereotype label is added dynamically into the notation file, and not into the UML model. It could generate refresh issues.

Property View Interface

to be edited

Conclusion

The retain solution will be the Single Label for each stereotype applied. An will be put in place as explained in a further chapter.

Solution Implementation

Architecture

Technically, the DecorationNode will be extended to create StereotypeLabel element into notation file. As well as for the stereotype properties.

Notation Model Structure

Structure into Notation file would be:

Label [type=StereotypeLabel][stereotype ="SysML::Allocations::Allocated"]
Compartment [type=StereotypeCompartment][stereotype="SysML::Allocations::Allocated"]
    Label [type=StereotypeProperty][property ="allocatedFrom=0..*" ]
    Label [type=StereotypeProperty][property ="allocatedTo=0..*" ]

Structure for the stereotype name Label:

DecorationNode (type = StereotypeLabel)
   stereotype(String: "SysML::Allocations::Allocated")
   Stereotype (Stereotype: "SysML::Allocations::Allocated")
   depth (String: None, Full, Auto, -1,-2,-3,...)

Structure of the property (to be defined):

BasicCompartment (type = StereotypeCompartment)

   stereotype(String: "SysML::Allocations::Allocated")
   element(Stereotype: "SysML::Allocations::Allocated")
   DecorationNode (type = StereotypeProperty)
      inCompartment (Boolean)
      inBrace (Boolean)
      inCommentCompartment (Boolean)
      inCommentBrace(Boolean)
      element( UML Property : AllocatedFrom )

EditPolicies Hierarchy

Here is the Class diagram that could be the solution for the new architecture:

Legend:

• AS = AppliedStereotype
• green block = new
• red block = modified
• blue block = not changed

To be completed

Intermediate Objectives

To plan the several steps of this whole improvement, it will be splitted into sub-goals.

All the objectives will be first fulfill for the Named Elements (like the Classes, Packages, ...) Once the new structure in place for those elements, it will be done for the other types of elements.

• Objective 1: Display all the stereotypes thanks to DecorationNode with one Label by stereotype.
• Objective 2:
  • 2a. Hide stereotypes thanks to CSS.
  • 2b. Display Qualified Name of some stereotypes thanks to CSS.
• Objective 3: Display all the properties into the compartment thanks to the DecorationNode into the notation file.
• Objective 4:
  • 4a. Hide the properties thanks to the CSS
  • 4b. Display properties into braces thanks to the CSS
  • 4c. Display properties into comment thanks to CSS.
• Objective 5: Create the graphical user interface into the Appearence Tab
• Objective 6: Propage objectives 1 to 5 to the other element throught their own edit policied.
• Objective 7: Plan a model transformation for a compatibility with old models using EAnnotation.

The following section details the progression of each Objective.

Objective 1

Display all the stereotypes thanks to DecorationNode with one Label by stereotype.

To fulfill this objective, the following steps should be completed:

1. Create and Delete StereotypeLabel through a Recording Command
   • Done
2. Create / Delete objects when stereotype is applied or deleted.
   • Done
3. Display the Label through the different EditPolicies
   • For Node Label: AppliedStereotypeNodeLabelDisplayEditPolicy
     • Done
4. Delete all usage of EAnnotation for the Stereotypes (Optionnal at this stage)
   • In Progress

Note: Done , means that the task is done but not already comitted. The entire Objective 1 will be committed at once when completed.

Objective 2

2a. Hide stereotypes thanks to CSS

1. Manage the isVisible parameter into the display of the Stereotype Label
   • • Done
2. Retrieve the "isVisible" value from the CSS
   • • Not required
3. Edit the CSS DOM Tree to match the NamedStyle Value
   • • Done

2b. Display Qualified Name of some stereotypes thanks to CSS

1. Manage the QualifiedName depth into the display of the Stereotype Label
   • • Done
2. Retrieve the "depth" value from the CSS
   • • Done

Objective 3

Display all the properties into the compartment thanks to the DecorationNode into the notation file.

To fulfill this objective, the following steps should be completed:

1. Create and Delete StereotypeProperty through a Recording Command
   • Done
2. Create / Delete objects when stereotype is applied or deleted.
   • Done
3. Display the Properties through the different EditPolicies
   • For Node Label: AppliedStereotypeNodeLabelDisplayEditPolicy
     • Done

Objective 4

4a. Hide the properties thanks to the CSS

1. Modify the CSS DOM tree to match the NamedStyle Selectors For "StereotypeProperty".
   • Done
2. Catch the CSS value to hide the corresponded Property.
   • Done
3. Modify the CSS DOM tree to match the NamedStyle Selectors For "StereotypeCompartment".
   • Done
4. Catch the CSS value to hide the corresponded Compartment.
   • Done

Encounter issue:

1. StereotypeProperties Labels are not created when CSS doesn't show the compartment
   • Solution: Notify "AppliedStereotypePropertyEditPolicy" when stereotype is applied. Using StereotypeElementListener instead of PapyrusStereotypeListener
     • Done
2. Error when refresh figure with an empty Property textFlow
   • Solution: Add condition on Text value during TextFlow creation into the AppliedStereotypeMultilinePropertyEditPart
     • Done

4b. Display properties into braces thanks to CSS.

1. Add The Location NamedStyle into Notation File
   • Done
2. Catch the CSS Value for the Location
   • Done
3. Calculate the New Text to display with Braces
   • Done

4c. Display properties into a comment thanks to CSS.

1. Create the Comment Object.
   • Done
2. Create the link between Comment and EditPart
   • Done
3. Calculate the text to display into the Comment
   • Done
4. Manage CSS property to display or hide properties into Comment
   • In Progress
5. Edit the Comment text content with the new text value
   • Not Started
6. Update Content when Stereotypes Applied or unapplied
   • Not Started
7. Delete Comment when empty
   • Not Started

Objective 5

Create the Graphical Interface to display Labels and Properties to override the CSS.

5a. Create the graphical user interface into the Appearence Tab

5b. Add the selection tree with appropriate collumn

5c. Add combo box with QN choices

5d. Add Tree commands to Expand / Collapse

5e. Add Tree commands to Select All / Deselect All

5f. Add Management rules (to be defined )

Objective 6

Propage objectives 1 to 5 to the other element throught their own edit policied.

• For External Node : AppliedStereotypeExternelNodeEditPolicy
  • Not Started
• For External Node label: AppliedStereotypeExternelNodeLabelEditPolicy
  • Not Started
• For Icon: AppliedStereotypeIconDisplayEditPolicy
  • Not Started
• For Link Label: AppliedStereotypeLinkLabelDisplayEditPolicy
  • Not Started

Objective 7

Plan a model transformation for a compatibility with old models using EAnnotation.

Open Points and Lessons learned

Open Points

• How an EditPolicy can be called when the Refresh (F5) of the EditPart is executed? It is required to refresh visual after applying a CSS.
  • It appears that the super Class GraphicalEditPolicy doesn't implement a refresh method, contrary to the internal class GraphicalEditPolicyEx
  • But this class is internal to GMF, so how make the refresh working for the Papyrus editPolicies.

• With CSS, how select a notation element with a specific StringValueStyle? For example with a StringValueStyle "name" with the value "Blocks"?

Lessons learned

• How a CSS selector can match on Notation Element likes [type="StereotypeLabel"] where "StereotypeLabel" is the type of a DecorationNode.
  • Clue : The class CSSDOMSemanticElementHelper defines rules to match the sementic Element of a notation view.
• How to define the way the CSS selector match elements?
  • Clue: The method doGetAttribute in the class GMFUMLElementAdapter return the corresponding element.

Tasks and Bugs

The bugzilla items tracking progress of this improvments are:

• Bug 457024