==== ABSTRACT ==== This artifact provides the implementation of the approach, which is based on EMF/Ecore and Xtext, referred to as “VirtualEdit framework” in the paper. It allows to take Xtext-based languages and exchange their default editor with VMXtextEditor, i.e., a VirtualEdit-provided one, to both (i) generate an editor that allows to dynamically show and hide the application of aspects developed in Henshin, where adding custom aspect orientation mechanisms is possible and has been done for the Java-like motivating example using the VMXtextEditor and (ii) generate an editor that allows to edit multiple model variants at the same time, where the model variants which are edited are derived by filename (not recommended) or specified in a simple language. ==== CONTENTS AND SETUP ==== This archive contains a VirtualBox Xubuntu-image containing the VirtualEdit framework, accompanied with examples, which can be retrieved from https://github.com/rbill/virtualedit/. The image contains an Eclipse installation with all projects already imported. Additionally, this Eclipse installation also contains Xtext grammars for the three working 'real-world' examples mentioned in the paper, i.e., ufoscript, (at.test.ufoscript, org.wesnoth.WML and test.Persistence). The projects have been generated by generating a default Xtext project and then replacing the content of the generated default Xtext file with custom Xtext files. The password of the testuser is a single blank (" "), if needed. It is recommended to give at least six GB of memory to the virtual machine. ==== BEWARE OF THE FOLLOWING INFORMATION BEFORE PROCEEDING ==== INFO 1: Although file changes are successfully saved, the Xtext editor keeps displaying a star at the end of the filename, i.e., indicating unsaved changes. INFO 2: Refrain from producing any other user input when waiting for the expected behavior to occur. Hence, please be patient after issuing input to produce a result. INFO 3: Please refrain from saving resources on exit and reloading files in an Xtext editor -- reload files in a text editor instead. INFO 4: Note that the overall code has been tested on the provided examples and described steps (only). INFO 5: We recommend to first close all projects, except the one to be executed. In case of malfunction, please restart Eclipse and re-execute the project. INFO 6: Note that the VJava and VAspect language are exemplary and thus allow producing source code that may be syntactically invalid in Java and AspectJ. INFO 7: The main eclipse instance ("VirtualEdit Eclipse") may not start if .xtend files are open (e.g. the ones you use for changing editors). Hence, please always close any open .xtend files before closing Eclipse. In case you forgot to do that and eclipse refuses to start, start Eclipse with the second Icon “VirtualEdit Eclipse (Reset perspective)”. ==== CONFIGURING A NEW XTEXT LANGUAGE ==== Two modifications were made for each project which are also required if other Xtext based languages are examined: * .ui/META-INF/MANIFEST.MF The bundle at.ac.tuwien.big.virtualxtext has to be added as required bundle. * .ui/src/.ui/...UiModule.xtend The lines import at.ac.tuwien.big.virtualxtext.MultiXtextEditor import at.ac.tuwien.big.virtualxtext.VMXtextEditor have to be added to to the imports The lines def Class bindXtextEditor() { //return MultiXtextEditor; return VMXtextEditor; } have to be added inside the class. If you want to execute the Multi-Model approach, you have to comment out the VMXtextEditor. If you want to execute the Aspect-orientation approach, you have to comment out the MultiXtextEditor ==== RUNNING-EXAMPLES (general) ==== For executing the modified editors, you need to right click on a plug-in project (e.g., at.test.ufoscript.ui or another project of the language you want to execute), then select Run As --> Eclipse Application. A second eclipse instance will start. This instance has a different workspace. It includes example files for the three working projects as well as the motivating bank example from the paper. If you want to execute an example, you should close all other projects (right click on the project folder and select 'close project') and open the project under investigation (right click - 'open project'). Please note that this implementation is prototypical and thus may be unstable and produces a set of debug messages. For example, saving invalid models may produce empty or invalid result files. For that reason, additional projects suffixed with 'Bak' are added which contain the exact same content as the normal projects. Therefore, in case such a malfunction occurs, please delete the content of the current project and replace it with the content from the 'Bak' project. Although file changes have been successfully saved, the Xtext editor keeps displaying a star at the end of the filename, i.e., indicating unsaved changes. Moreover, please note that opening and saving resources in the Wesnoth case will impair their formatting due to the handling of hidden tokens. ==== RUNNING AOP EXAMPLES ==== The goal of the editor for supporting aspect orientation is to simultaneously enable showing and hiding of aspects that are applied to a model as well as add the base model -- even in case aspects are applied. The execution of the provided example requires a respective Xtext language to use of the VMXtextEditor in the *UiModule.xtend, which is located in the package *.ui. For example, the Java-like language defines the class SimplejavaUiModule.xtend in package at.ac.tuwien.big.ui. The provided running example uses aspect orientation by default. AOP examples use the MultiView perspective. You can select the application of aspects by opening a file of the original language, e.g. test.ufo or test.vjava. Then, the VMXtextEditor first searches for applicable aspects, i.e. .henshin files for any language and .vaspect files for .vjava files and then applies and visualizes the modifications for each aspect in a different color. Moreover, the VirtualEdit view allows to select one or more of these aspects. In detail, a single model can be selected by left clicking on it or single models can be select/deselect by pressing CTRL and left clicking on them simultaneously. If a file with aspects applied is modified, then the base file will be edited. The source code, which is modified by aspects, can be changed as long as the aspect application is unchanged. The provided examples apply simple aspects to check whether they work in principle. Moreover, the VirtualEdit framework generates additional utility files. In particular, a .basic file is created to store the base code alongside the original-file, which contains the full, woven code. In case no original file exists, it is assumed that the base-code represents the full, woven, code. --- Example Run --- The example can be executed by following the steps listed below: STEP 1: Start the Runtime Eclipse instance, select "VirtualEdit view", and then open the "Item.vjava" file in the VirtualJava editor (pre-opened). Multiple colors indicate different aspects. STEP 2: Deactivate the "changepricesimple.henshin" rule by pressing CTRL and left clicking on the rule. The expected behavior is that the colored number “0” in "return 0" should be replaced by an uncolored “_price”. STEP 3: Replace “toString()” by “toString2()” and save. Then, refresh the “TestBank” project. You should see the “Item.vjava.basic” file containing, when opened in a text editor, a “toString2()”-method but no logging information. STEP 4: Open the "TraceAspect.vaspect” file using the "Aspect Editor". Then, change “_logger.logp((CLASS_NAME+("."+METHOD_NAME)))” to “_logger.logp((("In: " + CLASS_NAME)+(": executed "+METHOD_NAME)));” and “before()” to “after()”. Save the file. STEP 5: Close and Open the “Item.vjava” file within the “VirtualJava Editor”. The logging information is now displayed at the end of each method. ==== RUNNING MULTI-MODEL EXAMPLES ==== The goal of the multi-model editor is to be enable viewing and editing of multiple versions of the same model, simultaneously. The execution of the provided example requires a respective Xtext language to use of the MultiXtextEditor. The provided running-example “UFOScript” uses aspect orientation by default. Also, the preferred way to open such files is using “*.virtual.” files, e.g. “simple.virtual.ufo” in the “TestUFO” project. Although these files conform to the mmdesc language, Eclipse will show error markers as a result of the extension making it assume that it has to conform to the ufo language. The mmdesc part can be edited by opening the file with the text editor and has the following structure: PointDesc [String] <-- defines that each model should have a string parameter model 1 [] { <-- defines the root file with index 1, model 2 [] <-- defines a descendant file with index 2 model 3 [] <-- defines another descendant file with index 3 In order to execute these examples, the “FileURL” has to be adapted to match the location in your local file system. All file indices must be unique and should be as low as possible. This file defines which files are viewed together. The framework compares the changes between the root file and each subfiles, e.g. 1 and 2, 1 and 3, and displays the merged result. If this file is opened with the normal MultiXtextEditor (called e.g. 'UfoScript Editor'), it will merge the files and display all possible files in the VirtualEdit MultiView. This view allows to change the files that are displayed and edited (use CTRL + click to select/deselect a single model, click to select only a single model). When editing the model, you only edit the selected files. If values are highlighted in a color it means that they occur only in a specific model. Saving the .virtual. file triggers the saving of all the individual files that contributed to the merge. --- Example Run --- The example can be executed by following the steps listed below: STEP 1: Open the simple.virtual.ufo file in the UFOScript editor. It should display the content of the merged files simple.ufo, simple_1.ufo and simple_2.ufo. Here, e.g. the attribute highspeed does only occur in simple_2.ufo, the attribute newAttribute 22 only in simple_1.ufo. The attributes speed, maxspeed, and size have different values in some files. Here, the values of simple.ufo are used and the attribute marked in yellow. STEP 2: Open the VirtualEdit MultiView. CTRL-click on simple_1.ufo and simple.ufo. Then, the attribute 'highspeed 99' should go away as it only occurs in simple_2.ufo. STEP 3: Edit the 'newAttribute' attribute: Change the value from 22 to 23 and save the file. Open the simple_1.ufo file in a text editor to see that the attribute has changed there. Open simple.ufo and simple_2.ufo to see that the value has not been added there. STEP 4: Switch to the simple.virtual.ufo tab. Add a new attribute as last attribute, e.g. add "cost 999" before the last “}”. Save the file. Open simple_1.ufo and simple.ufo to see that the attribute has been added there. Open simple_2.ufo to see the attribute has not been added there as the file is not selected in the VirtualEdit MultiView STEP 5: Switch to the simple.virtual.ufo tab. CTRL-click on simple_2.ufo so that both simple_1.ufo, simple.ufo and simple_2.ufo are selected. Observe the 'cost 999' attribute has changed its color to grey to indicate it occurs in multiple files. ==== STRUCTURE OF THE CODE ==== LANGUAGES MULTIMODELDESC (at.ac.tuwien.big.multimodeldesc*) - The super-simple language used to describe mmdesc files, i.e. a language to define which models should be merged VASPECT (at.ac.tuwien.big.simpleaspect*) - The aspect language for vjava VJAVA (at.ac.tuwien.big.simplejava*) - The motivating example java-like language UFOSCRIPT (at.test.ufoscript*) - The UFO language (real-world test language) WML (org.wesnoth.WML*) - The WML language (real-world test language) SMARTHOME (test.Persistence*) - The persistence/smart home language (real-world test language) ACTUAL CODE PROJECTS VIRTUALXTEXT (at.ac.tuwien.big.virtualxtext) - contains both Xtext editors (MultiXtextEditor, VMXtextEditor) as well as the VirtualEdit view perspectives and helper content VIRTMODEL4 (VirtModel4) - Contains the main virtualization logic Important packages: at.ac.tuwien.big.vmod(.impl): The base virtualization at.ac.tuwien.big.vmod.ecore(.impl): The ecore compatibility layer at.ac.tuwien.big.vmod.provider(.impl): Base technology to provide models at.ac.tuwien.big.vmod.registry: Actual Aspect Orientation and Multi-model editors DEPENDENCIES AUTOEDIT (at.ac.tuwien.big.autoedit): This package searches for constraint violation fixes, but this feature is not used in this framework. OCLGEN (at.ac.tuwien.big.oclgen): This package serves for generating OCL code and provides several utilities. XTEXTUTILS (at.ac.tuwien.big.xtextutils): This package contains several utility features for handling the Xtext framework. Note that this package has been made available as part of the XMLIntellEdit repository, which is located at https://github.com/patrickneubauer/XMLIntellEdit/.