ETrice/GSoC/2013/Error Markers and Quick Fixes in State Chart Diagrams
This project aims at providing validation of State Chart Diagrams in the graphical editor of eTrice, a project under the Eclipse Model Development Tools (MDT) intended towards implementation of the ROOM Modelling language, by providing markers for warnings and infos in these state machine diagrams (in the eTrice behavior graphical editor) and quick fixes to allow the user to pick from a list of proposals.
Basic Understanding of the Project Idea
Q.1. What is ROOM?
ROOM (Real time Object Modelling) is both an object-oriented modelling language and a development method specifically designed for dealing with large distributed real-time embedded software systems characterized by event-driven or, reactive behavior. It supports automatic code generation to ensure reliability and increase productivity.
Q.2. What is eTrice?
eTrice is a project under Eclipse Model Development Tools (MDT) which provides an implementation of the ROOM modelling language in the following ways:
- It provides a textual editor (made in Xtext) for defining ROOM models in textual from.
- It provides graphical editors (made in Graphiti) for graphically editing the structure and behavior (i.e. state charts) parts of the actors involved in the model. These diagrams just contain layout information and any changes made in the graphical editor are reflected in the textual model.
- It provides code generators for the ROOM model in a variety of target languages like Java, C (ANSI-C), C++(under development).
- It provides Runtimes which give basic infrastructure like messaging and debug support.
Q.3. What problem are we trying to address?
While making a complex ROOM State Chart Diagram for an actor in the eTrice behavior graphical editor, the user might end up in an incomplete or invalid state machine, for example, the state machine might have some unconnected parts (or) their might be some unhandled incoming messages. The user will only come to know about these problems at the time of executing the model and depending on the error, it could be quiet difficult to identify the root cause which invalidates the model.
Q.4. What solution could be provided?
To address the above problem, there is a need to provide validation of the State Chart Diagram at the time of editing the model itself, i.e Extended Model Validation.
- The error identified with such a validation could be reported to the user by means of an error markers.
- Depending upon this validation and the error generated , the user could be provided with some kind of proposals for correcting the error, the so-called quick fixes for the error.
- Also depending upon the port & protocol interface of an actor, info markers regarding the valid messages which could be send, and moreover proposals for generating a valid state graph (states and transitions) could be provided (similar to content assist).
Q.5. What already exists?
To support the extended model validation, there exits an option to equip the protocols with semantic description defining the allowed message replies for each incoming message, the so called legal execution trees. Given these legal execution trees, an abstract state machine execution could be performed.
In the current scenario, this abstract state machine execution results in creation of warning markers in the textual model whenever a transition trigger doesn't catch a message which it should catch. Also info markers are generated at positions where a certain message is valid to send.
Q.6. What does the current idea adds?
Though the warning markers and info markers are present in the textual editor, these are not depicted in the behavior graphical editor, which is indeed the easiest and most intuitive way of editing the diagrams. As such this project aims at proving these results of validation in the diagrams of the behavior graphical editor.
Following things could be done in this regards :
- Provide visual feedback for warning in the diagrams.
- Provide Visual feedback for infos in the diagrams.
- Provide a mechanism to pick from a list of proposals to:
- correct the errors: quick fix.
- implement the info: content assist.
- Also, the graphical editor could be linked with the eclipse problems view.
- So, if the user double clicks on the a warning in the problems view (corresponding to extended model validation), then the corresponding problematic state/transition will be focused.
- Also, a mechanism for directly invoking the quick fix from the problems view can be provided.
Examples of similar implementations in other editors
This section elaborates on the details how exactly the visual feedback for warning and errors, and the list of proposals will be rendered on the diagram editor. Also, it would be discussed how the linking could be done with the problems view.
Listed below are a few images showing how some of the other projects have provided these features in their graphical editor :-
1. Here, error marks are being shown on the state:-
On clicking on the state with the state with error mark, it automatically open the editing dialog, along with showing the error with the state.
Also, a quick fix is present (the small bulb inside the editing box), which helps in fast correction of the error.
This could be done in eTrice for states where there are some unhandles messages. As soon as the user clicks on the state, the dialog for editing the transition could be opened and a quick fix for adding a new transition trigger could be provided.
Also this is linked with the Problems view.
2. Here the quick fix is being provided when the user double clicks on the error/warning in the problems view. The proposals are provided in a separate dialog box, on double clicking.
3. Here, the error markers are only listed in the problems view and a quick fix is a nearby dialog provided when the user double clicks on the state.
These are a few examples of graphical state machine editors implementing the features of validation, error markers and quick fixes. The motivation behind presenting them is to ensure that my thinking is in the correct direction. This also helps in materializing the expected deliverables.
A Possible Rendering Sequence to Adopt
Hence, one of the exact methods of rendering the features on the graphical editor could be as follows:-
- If a warning is generated by the extended model validation at the time of editing the state diagram, a warning marker (like examples above) will appear on the state.
- On hovering over the warning marker, the error would be displayed in the form of a tool-tip.
- A user could view the list of all quick fix proposals in a dialog which could be opened using one or more of the following mechanisms:
- Adding a context menu entry to the states and transitions which could be accessed by right-clicking on the respected diagram element.
- Adding a button to the Palette which would open the dialog.
- Double clicking the element with the warning marker.
- Similarly, an info marker could also be shown (probably using a different symbol). Again the info could be viewed by hovering over the element and the list of associated proposal could be shown by the mechanisms above.
- The Problems View can be linked to the graphical editor.
- While the user has opened the behavior graphical editor, double-clicking on a warning in the Problems view would lead to focusing over the corresponding diagram element with which the warning is associated.
- Also, the quick fix proposals could be viewed via an entry in the context menu associated with the warning in Problems view.
Phases of Development
The project implementation could be divided into four main phases:-
- Implementing warning markers & info markers.
- Implementing Quick Fixes.
- Linking the problems view with the graphical editor.
- Finalizing the unit tests, examples and documentation.
Each of the four phases will be elaborated below.
Implementing warning markers & info markers
- Initially, when the behavior graphical editor is first opened, the validation markers should be retrieved directly from textual editor (where the results of validation are already present) for each resource. This could be carried out by persisting the markers (in a generic way) and handling them inside the graphical editor after retrieval.
- Since the contents of textual editor are not updated until the diagram is saved in the graphical editor, we cannot use the same method of retrieving the markers from the textual editor after update. Hence, there is a need run separate validation after each editing step and update the markers in the graphical editor, rather than waiting for the user to save the diagram and then retrieve the markers.
- So, on subsequent editing, after each editing step, the validation should be run and the results must be updated on the diagram. (This could be carried out in a custom CommandStackListener).
- For the frequent validation during editing, rather than running the complete validation, it might be favorable to restrict the validation, say, to reachability testing and extended state machine validation only.
- As soon as the diagram is saved, complete validation would automatically be carried out and the results of validation would again be present in the textual editor. So, we go back to retrieving the markers(task 1) and the cycle repeats.
Implementing quick fixes
- First, for each kind of warning and info, a list of quick fix proposals need to be generated.
- Then, this list of quick fixes must be rendered on the diagram by an event/mechanism like double click or clicking a button on the Graphiti’s context button pad.
- Once the user chooses a particular proposal, the corresponding changes must be implemented in the diagram (like addition of new states and transitions) keeping in mind the layout of the diagram elements on the canvas.
Linking the problems view with the graphical editor
- Warnings entries must be generated in the problems view for warnings in graphical editor.
- On double clicking, a warning entry inside the problems view, the associated diagram element must be highlighted.
- Quick fix proposals should be provided as a part of the context menu of these entries in problems view (as is the case in general).
Finalizing the unit tests, examples and documentation
- Writting unit tests to help avoid any bugs at later stages and prove the correct working of the features in various circumstances (like breakdown in the dependency chain, etc.)
- implemented example ROOM models to demostrate the feature.
- An important part of this phase is to provide extensive documentation for the users(as a part of eclipse help) and for the developers(as extensive JavaDoc comments) for helping them use this new feature and for allowing easy further extension and usage respectively.
Calendar for development calls
A superficial schedule of the project would be as follow:
Before 6 May: Preparing the project Wiki and improving the understanding of the implementation process.
Before the beginning (Community Bonding Period)
6 May - 26 May: Gathering the background knowledge as indicated by above sections(Background), Detailing of the schedule to make it more rigid and easily tractable.
I Phase (Implementing warning markers & info markers)
27 May - 2 June: Initial Validation - Persisting and Retrieving markers from textual editor
3 June - 9 May : Initial Validation - Representing markers on diagram elements when opened Initially.
10 May - 16 June : Continuous Validation - Implement restricted Validation.
17 June - 23 June : Continuous Validation - Implementing Validation after each editing step & update editor
24 June - 30 June : Continuous Validation - Update the editor after validation & on saving the diagram.
II Phase (Implementing Quick Fixes)
1 July - 7 July: Generate a list of quick fix proposals for all warnings.
8 July - 14 July : Render quick fix proposals over the diagram editor & implement actions to be taken.
15 July - 21 July : Implement actions to be taken on selecting a proposal.
21 July - 28 July: Combining all implementations from Phase I and Phase II for preparing a stable version for mid-term evaluation.
29 July - 2 August : Mid-Term Evaluation & Feedback reception
III Phase (Linking the problems view with the graphical editor)
2 August - 11 August: Implement generation of warning entries in problems view.
12 August - 18 August : Implement navigation from problems view to editor; Adding quick fixes (generated in Phase II) into context menu of warnings.
IV Phase (Finalizing the unit tests, examples and documentation)
19 August - 25 August: Recheck all unit tests and implemented unimplemented unit test.
26 August - 1 September : Write complete user documentation and demo examples (ROOM Model).
2 September - 8 September : A backup week(if something runs out of schedule). If everything on time, then proceed to final review phase.
Final Review and Feedback
9 September - 15 September: Final review, community feedback and minor corrections.
Click Here to see the project proposal at GSoC's website.