ETrice/GSoC/2014/Target language aware action code editors for eTrice
This project aims at providing target language aware editors for the editing the action code (written in Detailed Level Language) embedded inside the state machines of eTrice, a project under the Eclipse Model Development Tools (MDT) intended towards implementation of the ROOM Modelling language, by proving editors with syntax highlighting & model aware content assist within the property dialogs of transitions & states. Moreover, additional dialogs would be provided for editing the operations & user code of actors and for editing the protocol classes.
- 1 Basic Understanding of the Project Idea
- 2 Implementation Details
- 2.1 Basic Technical Details
- 2.2 Phases of Development
- 2.3 Schedule
- 2.3.1 Before the beginning (Community Bonding Period)
- 2.3.2 I Phase (Implementing the backbone plugin environment)
- 2.3.3 II Phase (Implementing editable Java action code viewer & maximization)
- 2.3.4 III Phase (Implementing editable C/C++ action code viewer)
- 2.3.5 IV Phase (Implementing dialogs for operations & protocol classes)
- 2.3.6 V Phase (Finalizing the unit tests and documentation)
- 2.3.7 Final Review and Feedback
- 3 Project Proposal
- 4 Useful Links
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 form.
- It provides graphical editors (made in Graphiti) for graphically editing the structure and behavior parts (i.e. state chart diagrams) 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 problems are we trying to address?
Within the state machines(behavior part) of the actors of a ROOM Model are embedded action codes which are executed when a state is left or entered, or when a transition is traversed. These action codes are written in what is called a Detailed Level Language(DLL) which is same as the target language for code generation for the model. The action code could be inserted both from the Textual editor (within the code written in Xtext DSL) and from the behavior graphical editor (through the properties dialog of states & transitions). Currently, there is only a plain text edit field available in the properties dialog to edit the action code, thus depriving the user of rich editing feature like syntax highlighting, content assist and model awareness.
Another missing feature within the behavior graphical editor is that, there is no method to insert operations & user code lines from within the graphical editor. Each time the user wish to add operations to the behavior part, they have to edit the code in the textual model directly. This increases the learning curve for a new user who is more comfortable working with the graphical editor.
Similarly, there is no way to define & edit protocol classes from within the structural graphical editor.
Q.4. What solution does the current idea intends to provide?
The projects aims to solve each of the above problems in the following manner :-
- For the purpose of making the editing of action code more intuitive and user friendly, we intend to provide a more advanced source code editor within the properties dialog with the minimal set of features such as:-
- Syntax highlighting
- Content assist on the model level. This implies generating proposals for actor’s attributes & messages that can be sent or received inside the editor.
Since the action code is dependent on the target language, different editors need to be provided for each of the available target languages (at present, Java and C/C++).
- For inserting, editing & viewing the operations & user code from within the behavior graphical editor, a new dialog is intended to be provided. The aim would be to automate the task of manually writing the operations & user codes in textual DSL editor by means of various selection & drop-down menu widgets in JFace dialog.
- Similar to the case of operations & user codes, a dialog is intended to be provided for the purpose of generating and editing protocol classed.
Basic Technical Details
For the purpose of providing an editable widget with syntax highlighting & content assist inside the properties dialog, we propose to use the JFace SourceViewer.
After enough research, it was confirmed that a full-fetched workbench editors cannot be directly included inside a Dialog in eclipse as the functioning of such an editor requires many features provided by the workbench. On the other hand, the JFace SourceViewer perfectly fits our required use case and also has a well defined configuration methodology(using the SourceViewerConfiguration) to configure syntax highlighting and content assist within itself.
Also, realizing the need to have flexibility in adding new viewers to the dialog for other target languages and middle-wares(other than C/C++ & Java) which are still not supported in eTrice but might be added in future, it would be desirable to have a loose coupling of the source viewer with the dialog. This could be easily achieved inside the eclipse plugin development environment which support in-exhaustive extensibility by means of Extension Points and Extension. We intend to define an Extension Point for adding external widgets to the dialog and implement the SourceViewers within new extensions which extend the constructed Extension Point. Preferences within the Extension Point would help select the correct Viewer for the target language. Apart from flexibility, this has a huge advantages of affecting the current code to the minimum.
Phases of Development
The project implementation has been divided into five main phases :-
- Implementing the backbone plugin environment.
- Implementing editable Java action code viewer & maximization
- Implementing editable C/C++ action code viewer
- Implementing dialogs for operations & protocol classes
- Finalizing the unit tests and documentation.
Each of the five phases have been elaborated below.
Implementing the backbone plugin environment
In the first phase, the main task would be to establish the plugin environment within the current plugin structure of eTrice, to allow addition of widgets inside the dialog by external Extensions. For this an Extension Point would be implemented inside the dialog containing plugin and the dialog code would be suitably modified.
Implementing editable Java action code viewer & maximization
In the second phase, we would go ahead with the implementation of SourceViewer for the target language Java within the plugin environment, which was set up in the first phase. In this, the main task would be to configure the SourceViewerConfiguration correctly for :
- Syntax Highlighting in Java
- Content Assist in Java along with including the details of the model.
A good starting point to accomplish the above would be to use the JavaSourceViewerConfiguration which already implements syntax highlighting and content assist for JFace SourceViewer.
Also, maximization of the SourceViewer Widget would be implemented.
Implementing editable C/C++ action code viewer
The third phase would involve implementing SourceViewer for target language C & C++, again with the primary focus of configuring SourceViewerConfiguration correctly for syntax highlighting, and content assist in C++ along with including the details of the model.
Here, a great amount of help could be taken from the CDT project with accomplishes both the tasks in its editors. It is intended to collect more information of previous such implementations during the Community Bonding Period and then finalized after consulting with the mentors.
Implementing dialogs for operations & protocol classes
For the fourth phase, the task would be to implement dialogs for editing operations & user codes in the behavior graphical editor, and editing the protocol classes inside the structure graphical editor. The aim, as already stated, would be to automate the task of manually writing the operations in textual editor by means of various selection & drop-down menu widgets.
The implementation of both the dialogs could be divided into four main tasks :
- Making the GUI of the JFace dialog with proper widgets.
- Populating the dialog widgets with model data.
- Changing model correctly on submit.
- Making a separate context menu entry for launching the dialog within respective editors.
Finalizing the unit tests and documentation
The fifth phase is dedicated to writing and finalizing the unit tests as well as the documentation.
- Enough unit tests would be written 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.)
- Also the proper working of the implementations would be confirmed by performing manual checks on a number of varied models.
- 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(like adding editor widget for another target language) respectively.
- It is intended not to leave the complete documentation and testing until the fifth phase. Indeed the fifth phase only involves finalization of the tests and documents written in each week. (See the Schedule for the general schedule for each week ).
A superficial schedule of the project would be as follow:
Before 3 May : Preparing the project Wiki and improving the understanding of the implementation process.
Before the beginning (Community Bonding Period)
3 May - 18 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 the backbone plugin environment)
19 May - 25 May : Constructing plugin Extension Point and Preferences
II Phase (Implementing editable Java action code viewer & maximization)
26 May - 1 June : Implementing syntax highlighting & basic content assist in SourceViewerConfiguration for Java.
2 June - 8 June : Implementing Model aware content assist in SourceViewerConfiguration for Java.
9 June - 15 June : Implementing maximization of SourceViewer widget for easier editing.
III Phase (Implementing editable C/C++ action code viewer)
16 June - 22 June : Implementing syntax highlighting in SourceViewerConfiguration for C/C++.
23 June - 25 June : MidTerm Evaluation - Preparing a stable version for mid-term evaluation & Feedback reception.
26 June - 29 June : Implementing basic content assist in SourceViewerConfiguration for C/C++.
30 June - 6 July : Implementing model aware content assist in SourceViewerConfiguration for C/C++.
IV Phase (Implementing dialogs for operations & protocol classes)
7 July - 13 July : Implementing dialog for operations & user code (GUI + Population).
14 July - 20 July : Implementing dialog for operations & user code (model modification on submit) and for protocol class (GUI + Population).
21 July - 27 July : Implementing dialog for protocol class (model modification) and provide context menu entries.
V Phase (Finalizing the unit tests and documentation)
28 July - 3 August : Implemented unimplemented unit test and write complete user documentation.
4 August - 10 August : A backup week(if something runs out of schedule). If everything on time, then proceed to final review phase.
Final Review and Feedback
11 August - 17 August : Final review, community feedback and minor corrections.
eTrice Project Links
JFace Source Viewer
- Source viewers and annotations - Eclipse Online Help
- Configuring a source viewer - Eclipse Online Help
- SourceViewer - API
- SourceViewerConfiguration - API
Platform Text Editor & Examples
These have been used to take ideas for configuring Source Viewer and construction of custom API for Dialogs.
- IBM Article
- Building an Eclipse Text Editor with JFace Text
- Introduction of Eclipse editors
- Using the SourceViewer with Annotations separately from a TextEditor
- Developing content assistant for Eclipse plugins - Keybinding Example