Palladio Developer Wiki

Palladio Addon (Liste)
Name	SimuLizar Usability Extension
Contacts	Steffen Becker (https://www.uni-stuttgart.de/presse/experten/Prof.-Dr.-Steffen-Becker/)
State	Stable
Is Stand-alone Analysis?	No
Extends Analyses
Extends Metamodels

Short Summary

SimuLizar is a Palladio plug-in for analyzing self-adaptive systems. To analyze such systems, SimuLizar introduces new metrics to the PCM: Scalability, elasticity and efficiency. This is achieved by using Monitors, Measuring Points and multiple measurable metrics. With the SimuLizar Usability Extension we want to aid users in the prozess of managing and creating these through a new Measurements-Dashboard view with an integrated wizard.

Documentation

The SimuLizar Usability Extension is a Palladio plug-in for helping users define measurments in their Palladio project in order to simulate their system through the SimuLizar plug-in. Before executing the simulation users have to define the parts of their system they are interested in. This Prozess is implemented through the concept of Monitors and Measuring Points. To understand the following user and developer guide we provide definitions for important terms according to the QuAL documentation of SimuLizar:

Monitor: A Monitor is used to specify what should be measured in a system. It consists of one Measuring Point and a List of Measurement Specifications. Monitors are evaluated during a simulation in order to compute the results of the simulation.
Measuring Point: A Measuring Point defines where to measure. It corresponds to a model element of the system.
Measurement Specification: The Measurement Specification describes the collected Measurement. It contains a Metric Description and a Processing Type.
Metric Description: A Metric Description characterizes metrics to be measured. It consists of a textual description, the capture type, the unit and the scale.
Processing Type: The Processing type defines how measurements should be collected and recorded for the result of the simulation.
Measurement: Measurements specify data objects for storing measuring values at a given measuring point; typed by a corresponding metric description. We further use 'Measurement' to reference the combination of a Monitor with an Measuring Point and Measurement Specifications as one term.
Monitor/Measuring Point Repository: A Repository is used to store and manage a set of elements.

User Guide

The SimuLizar extension provides the possibility to create Monitors and Measuring Points for a Palladio project and to specify measurements. It combines a dashboard-view with multipurpose wizards which guide the user through the entire process.

The main goals of SimuLizar extension consist of the following:

Guide the user through the entire process, in this way reduce the potential confusion of which step to take next.
Give suggestions and explanations for novice users.
Provide enhanced features for experienced users.

To use the SimuLizar extension the user should have:

Java Platform JDK 8+
Eclipse Modeling Framework
Palladio Component Model
Eclipse EMF Parsley (not necessary if you already installed the latest Eclipse Modeling Tool)

To install the SimuLizar extension, users need to download the latest Eclipse Modelling Tools Edition and install Palladio from the above mentioned link.

The users who use the SimuLizar extension should firstly create a Palladio project which should be based on EMF Model. The following link includes a workshop to create an example web application using Palladio.

After the Palladio project is successfully created, the users need to open the SimuLizar perspective. This view contains a dashboard that represents the actual state of Monitor and Measuring Points of the Palladio project with its parameters. In the dashboard, the user can filter both Monitor and Measuring Point names with help of a provided search box. Through the dashboard, the state of the Monitors can be set. The dashboard also provides a Create Standard Set option which automatically creates Monitors and Measuring Points for the novice users depending on their Palladio project.

In addition to the dashboard, users are able to manipulate Monitors and Measuring Points using wizards which guide the user. Using the wizard perspective, users are lead through a step-by-step process where they can choose different options and different parameters. They can create a Monitor, select a Measuring Point, choose Metrics which can be used with the selected Measuring Points. Optionally, the 'Suggestion' function for common options are provided to novice users in the third page of the wizard. At the end of each wizard, the specified Monitors and Measuring Points are automatically created and assigned to their respective models within the system.

A complete Use-Case Tutorial of the Wizard explaining all major features can be found here: SimuLizar Usability Extension - Use Case Tutorial

Measurement Dashboard

The 'measurement dashboard provides an overview of all existing monitors and measurement points without assigned monitors. In combination with the measurement properties view it offers the basis to edit, save or delete Monitors, Measurement Specifications, Measuring Points and Processing Types. It also creates a connection to the wizard implemented by us in order to create new monitors and measuring points or to edit them. In case something in the PCM Models has changed the view can be updated by pressing the key F5.

1. With the project combo box, a project in the workspace can be selected, which data is shown to the user. Only data of one project can be displayed at a time.

2. The monitor repository combo box can be used to choose a monitor repository of the previous project. The data of the selected monitor is then displayed in the monitor repository tree (see 3.). If only one monitor repository exists in the project this value is fixed. Otherwise, the user can select a repository from a list.

3. You can filter both the monitory repository tree and the empty measuring points tree by typing the name of a measurement. Keywords such as Monitor, MeasuringPoint, MetricDescription, Measurement Specification and Processing Type are also supported. In addition, the monitor repository tree can also be filtered for active or inactive monitors by the two checkboxes at the end.

4. The monitor repository tree viewer shows all monitors of the in 2. selected monitor repository. For each monitor, its measurement specifications and processing types are also displayed as child nodes. More detailed properties of an element in the tree can be shown and edited using the measurement properties view.

5. The empty measuring points tree viewer shows all measuring points out of all measuring point repositories of a project which are not assigned to a monitor yet. Measuring points can be assigned to monitors via drag and drop. If a monitor already contains a measuring point, both measuring points will be exchanged.

6. Clicking on the Add new Measurement button opens the first wizard page where you can create a monitor with an existing or new measuring point.

7. Based on the selected item in the view, the user can edit or delete measurements. Editing a measurement opens the corresponding wizard of the selected item. Editing a monitor opens the monitor creation wizard page, editing a measurement specification links to the metric description selection page and editing a processing type starts the wizard on the processing type selection page. Clicking on the delete button deletes the selected resource. If the functionality of a button is not provided for a selected item, the respective button will be disabled.

8. The create standard set buttons opens the create standard set wizard workflow.

Monitor Creation Page

In the first step of our wizard, you need to create a Monitor. The user can specify the name for the new monitor to be added. Furthermore the user has the possibility to set the monitor to active or inactive.

The user can also use the Edit button in the dashboard to get to this page where he can change the name or switch between active and inactive and immediately close the page using the Finish button.

Monitor Creation Page

Measuring Point Selection Page

In the second step of our wizard, you need to add a measuring point to it. The wizard supports the creation of eleven different measuring points, they are listed in the table below.

Measuring Point	Main Model Element	Second Model Element	Third Model Element
Assembly Operation Measuring Point	Assembly Context	Operation Role	Operation Signature
System Operation Measuring Point	System	Operation Role	Operation Signature
Subsystem Measuring Point	Subsystem	Operation Role	Operation Signature
Assembly Passive Resource Measuring Point	Assembly Context	Passive Resource
Active Resource Measuring Point	Processing Resource Specification
Linking Resource Measuring Point	Linking Resource
Usage Scenario Measuring Point	Usage Scenario
Entry Level System Call Measuring Point	Entry Level System Call
External Action Call Measuring Point	External Action Call
Resource Environment Measuring Point	Resource Environment
Resource Container Measuring Point	Resource Container

The wizard provides help and structure to the process of the creation of a measuring point. You can choose model elements for the measuring point creation by either selecting them and then clicking on Next or by double-clicking on the element.

The UI of the wizard page consists of the following elements:

1. This is the information message of the wizard page. When first opened, it gives a short explanation of the purpose of the page. However, when you select any element from the tree, it shows what kind of measuring point can be created from the element. If you select any element, which does not correspond to a measuring point, it will give you an error message and prohibit you from proceeding by disabling the next button.

2. The wizard page has two tabs, one for the creation of a new measuring point and one for the selection of an existing measuring point. In either of those you can select an element and proceed with the next steps. If you are editing an existing element, it will select the measuring point which is already added to the corresponding monitor.

3. In the Create new measuring point tab, you have to possibilities to display your models: A hierarchical view and a flat view. In the hierarchical view, the wizard page gives you all elements, from which a measuring point can be created and their hierarchical parents, while omitting the elements, which can't be measured. In the flat view, it only gives you the elements, from which a measuring point can be created. However it provides you with the name of the parent element, if possible, so you get at least some sense of the location of the model element.

4. You can filter the trees by name. The filter works by using the name of the element. In the hierarchical view it preserves the hierarchy.

5. This is the tree of elements. When first opening the wizard page while creating a new measurement, the first element, from which a measuring point can be created, will be selected. When you open the wizard via the Editing button, it will open the Select existing measuring point tab and have the corresponding measuring point selected. Elements from which a measuring point can be created, have a bold font, so you can see immediately, which elements can be selected for measurement.

6. This is the help button of the wizard. If clicked it will open the wiki page you are currently reading.

7. The page also has the normal Back, Next, Cancel and Finish buttons. You can always go back to the first page and cancel the wizard, the next button can be disabled, depending on your selection in the tree and the finish button is enabled if you already selected a measuring point and a measurement from the next wizard page.

Here you can see the how the tab for existing measuring points and the flat view of the tree of the creation of a new measuring point look like:

For some measuring points, you need to specify multiple model elements. In the table at the top of this section you can see for which this is the case. In that case you will have additional wizard pages where only the fitting model elements will be shown:

Metric Description Selection Page

The user can specify the metrics, which they want to measure with their software system. In order to select a metric, the users should choose a measuring point from the second page of the wizard. After a measuring point is selected, the available metrics will be shown on the left table of the third page. On that page, users can choose one or more of these metrics which will be used with the previously selected measuring point.

The following picture shows the view of the metric selection wizard page. As an example, the usage scenario measuring point from the previous page has been selected. Two metrics are assigned to this measuring point to be used with the according monitor which is specified at the first wizard page. If the user clicks on a metric, an explanation is provided at the top of the wizard page where the user can learn more about it.

The users can also define a reconfiguration rule for their measurements by marking the Self Adaptive option in the wizard page. For instance, if the server's CPU utilization is more than 80%, a second server will be added to the system and it will be reconfigured by SimuLizar.

On that wizard page, users can move all available metrics to the right table with the Add All button. However, the users are able to move the metrics one-by-one using the Add button or with the Drag and Drop feature.

The Add Suggestion button is provided for the novice users who are not totally sure which metrics should be added to the right table. Using that button, a set of suggested metrics are added to the right table. The users can reset their changes on the wizard page pressing the Remove and RemoveAll buttons.

The Back button returns to the previous page, where the users can change the measuring point. The Next button directs the user to the processing type selection page. The Cancel button cancels the complete wizard workflow, not saving any changes or additions that were selected since the wizard window was opened. The Finish button saves all changes, stores the current state of the wizard and shows them on the dashboard.

Finally, clicking on the Help symbol that is located at the left bottom side of the wizard, the users will be redirected to the according section of this Wiki-Site.

Processing Type Selection Page

After selecting metric descriptions in the third page, we offer users the ability to further specify the processing type of the metric description. By default, feed through is selected, which needs no further property values specified.
The possible processing types that can be selected are:

Feed Through (default)
Fixed Size Aggregation
Time Driven
Time Driven Aggregation
Variable Size Aggregation

Changing processing types can be done by clicking in the processing type field, which then offers a drop-down with all possible types. If property values need to be specified they are automatically shown depending on which processing type is selected. Furthermore, the property values are always given their default values when the processing type is initially selected.

The back button returns to the previous page, where you can change which metric descriptions <-> measurement specification pairs are assigned to the monitor.
Since this is the last page in the wizard, it is not possible to press the next button.
The cancel button cancels the complete wizard workflow, not saving any changes or additions that were selected since the wizard window was opened.
Pressing the finish button adds the monitor to the monitor repository with the attributes that were selected during the wizard workflow.

Standard Set Functionality

The create standard set button allows the automatic creation of monitors as-well as measuring points. The standard set creation has its own wizard workflow, allowing a choice if only new measuring points should be created, or new monitors with new measuring points, that are directly assigned to each other.
Choosing which action to perform is done in the first screen of the wizard.

Standard set for monitors and measuring points

If the first option create monitors and measuring points is selected, the user is presented with a list of all model elements for which the monitor <-> measuring point pairs can be created.
Model elements to create measurements for can be selected through the checkboxes on the left of the wizard page. Furthermore, pressing the select all or unselect all buttons allows selection/deselection of all fields.
For each selected checkbox a monitor and a measuring point is created. The measuring point is assigned to the monitor. Each measuring point has suggested metric descriptions, which are specified through our extension point. For each of these suggested metric descriptions a measurement specification is created. The metric description is set in the measurement specification. This pair is then assigned to the monitor. Lastly, the default processing type feed through is assigned for each metric description.

Standard set for only measuring points

If the option create only measuring points is selected, you are presented with the same view as before, model elements can be selected through checkboxes. The main difference is that only measuring points are created for each element that is selected. These points are not assigned to any monitors. They can be later assigned to monitors through the dashboard through dragging a measuring point onto a monitor.

Use Case Diagram

This is the use case diagram of the measurements ui extension

Developer Guide

In this section we will describe how we developed the Measurements-Dashboard with the wizard, which technologies we used, how to adapt them and how to extend this project.

Palladio as a project extends the Eclipse IDE. In other words, Palladio is not a independent program you need to start, but instead it extends the existing Eclipse developement environment with further concepts and models. Our project extends the Eclipse IDE with an additional view and functionality in the same way. If any of that is new to you, here are some starting points about how the so called Eclipse IDE Plug-in Developement functions:

Another concept you should be familiar with is EMF, the Eclipse Modeling Framework. This framework can be used to design your own models of structured data and helps you with building tools for users to interact with your models. All the Palladio models are based on EMF, so for example for a Monitor there exist an EMF model, which defines what a Monitor is, what attributes he has and how he is connected to other models. Important for developement is, that there are corresponding Java Classes to each model, which are all so called "EObjects". When we talk about Palladio elements in the following section, like Monitors, MeasuringPoints, MetricDescriptions etc., we are always referrencing the corresponding EObject. If you are not familiar with this concept and all the built in development possibilities, here are some starting points:

SimuLizar Usability Extension Project

The component diagram of the usability extension

The main contribution of our project is a new Eclipse view called "Measurements Dashboard" in the categorie SimuLizar and in the SimuLizar Perspective. If you want to know more about what it includes and how to use it look at the User Guide. In the following sections we will explain how we developed this view and all its functionality and how you can extend it. Before you can extend it you need to make sure, that you have everything installed to open and contribute to our project. The easiest way to get all you need is to:

Install a version of the Eclipse Modeling Tools and Palladio according to the PCM Installation Guide.
Install SWTBot from their side: It is used for GUI-Tests in our project.
Clone our Git repository and import it into your workspace: In Eclipse open the "Git" perspective (type in "Git" in the "Quick Access" bar in the top right and click on it) and choose the "Clone a Git Repository and add the clone to this view" option. Insert the URL you get when you klick "Clone or download" on our Github site into the URI field. In the next step select the "dev" branch to get the newest working version of our project and save the repository on your disk on the last step. Then switch back to the "Package Explorer" and import our project by right-klick -> import -> Git -> Projects from Git -> Existing local repository -> Select your repository -> finish

After you are set up and ready we will now explain the components of our project and how they work in detail. On an abstract level, our project consists of two modules. The data module consists of our data structure and providers to change and edit it. The view contains the Measurements-Dashboard and the wizard with his four pages. You can see these two modules in the component diagram on the right. Our data structure is defined and managed by the Dataprovider component. The Datamanipulation component is used by the Dataprovider to change data. The Wizardmodel serves as interface to the corresponding Wizard component in the view. It is used to provide the necessary data to the view and the functionality needed to change this data. The Dashboard receives the required data directly from the Dataprovider.

Data Component

The data project consists of multiple packages used for creating and modifying objects during the wizard workflow. The below diagram presents all packages including its classes and the interaction between classes. In total, there are five different packages. The five packages are:

Fileaccess - Used for accessing the models from the projects out of the workspace. Used by the DataApplication for initialization.
Datamanipulation - Provides the functions for creating, deleting and modifying objects, mostly used by the DataProvider.
Dataprovider - Provides the functions used by the corresponding wizard pages.
Wizardmodel - Manages the wizard pages and their workflow.
WizardmodelPages - Manage the actions of the single wizard pages.

In the diagram we omitted some links between classes for visability reasons. For example every class in the WizardmodelPages package is linked to the corresponding provider in the Dataprovider package. We also omitted the parameters of methods which would have gotten to long to fit into the diagram.

Fileaccess Package

The Fileaccess package is used to get access to the necessary files and models from the eclipse workspace of the user.

With the ValidProjectAccessor we gain access to the projects in the workspace of the user. You can examine these projects with the following code snippet:

IWorkspaceRoot wsRoot = ResourcesPlugin.getWorkspace().getRoot();
      IProject[] wsProjects = wsRoot.getProjects();

In our case we filter these projects further to look for a ".aird" file which marks the project as modeling project in eclipse. We only work with modeling projects in our UI since we load the Palladio models through a Sirius session. For this purpose this class offers a method to get the ".aird" file given a project.

In the ModelAccessor we manage all Palladio models that are present in a eclipse project. Given a Sirius session, the ModelAccessor initializes the EObjects corresponding to the five Palladio core models (Allocation, Repository, System, ResourceEnvironment, UsageModel) as-well as the MonitorRepository and the MeasuringPointRepository, if they exist. If there is no MonitorRepository or MeasuringPointRepository they are created automatically by utilizing the RepositoryCreator. All objects are stored in a list, since it is possible that the user created multiple instances of each model. Furthermore this class offers a function to get all unassigned MeasuringPoints. This includes every MeasuringPoint that is not assigned to a Monitor, no matter from which MeasuringPointRepository. Access to the models stored in this class is managed by the DataApplication.

Datamanipulation Package

The Datamanipulation package provides the basic functionalities for creating, deleting and modifying EObjects. Since existing EObjects cannot be modified without EMF transactions, the DataEditor class provides the basic functionalities for working with objects, which are then further specified for our usages in the ResourceEditor class. The DataEditor utilizes the EMF SetCommand, AddCommand and DeleteCommand on the passed object's Editing Domain.

For example, the editResource function takes an EObject, the attribute String feature to change, and a new value.

public void editResource(EObject element, String attribute, Object newValue) {

        EditingDomain domain = AdapterFactoryEditingDomain.getEditingDomainFor(element);
        domain.getCommandStack()
                .execute(new SetCommand(domain, element, element.eClass().getEStructuralFeature(attribute), newValue));
    }

The ResourceEditor takes the functions from the DataEditor and correctly applies the commands depending on the attribute of the EStructuralFeature. These functions are used by the WizardModelManager, mainly for saving when finish is pressed in the wizard, or for undoing the command stack when cancel is pressed and by different DataProvider classes. For example the following function utilizes the editResource function to set the measuring point to a monitor. Here the monitors EStructuralFeature for the measuring point is called "measuringPoint".

public void setMeasuringPointToMonitor(EObject monitor, MeasuringPoint mp) {
        editor.editResource(monitor, "measuringPoint", mp);
    }

The Datamanipulation package also contains the RepositoryCreator class, which offers functionality for creating repositories, should none exist.

Dataprovider Package

The Dataprovider package provides the functions for the various wizard pages as-well as for the standard set creation. Furthermore the DataApplication provides the MeasurementsDashboardView and the Wizardmodel with access to the projects and models from the workspace. The DataApplication primary function is to initialize a session depending on the current project. For this purpose we manage the Eclipse project the user is currently working with. Through the ".aird" file of this project we can initialize a Sirius session which contains all EMF Resources of the models through which we can get access to the corresponding EObjects. Additionally to the project, we manage the currently selected MonitorRepository, since the user has the option to work with multiple ones.

The MonitorCreationProvider class implements the functionality to edit the name of a monitor an change it's activated status.

The MeasuringPointModelElementProvider class provides access to all Palladio component models, present in the project, which can be selected to create a MeasuringPoint.

The UnselectedMetricSpecifcationProvider class contains functions for the third wizard page, which allows selecting the required metric descriptions. Utilizing parsley, we first create a temporary monitor with all of the valid metric descriptions, that are not already in the monitor we are using during the wizard workflow. Since metric descriptions are applied to measurement specifications one-to-one and the measurement specifications are then applied to the monitor, we need to create a measurement specification <-> metric description pair for every metric description that is shown in the parsley monitor. These pairs are then moved back and forth between the two monitors, depending on the buttons or drag-n-drop actions the user performs. We have to differentiate if the user is working with a new monitor, or editing an existing monitor, since when working with an existing monitor it is necessary to use the EMF Commands from the ResourceEditor to avoid EMF writeTransaction errors.

The ProcessingTypeProvider class provides the fourth page, responsible for selecting processing types, with the correct information. The class contains functions to provide the possible processing types, set and get new or current processing types and to modify the processing type attributes for every measurement specification <-> metric description pair. The processing types that can be selected are:

Feed Through (default)
Fixed Size Aggregation
Time Driven
Time Driven Aggregation
Variable Size Aggregation

Since the UI utilizes a drop-down to select the processing type, we update the corresponding attributes depending on the user selection from the drop-down. The ProcessingTypeProvider Class provides the information and functions to the ProcessingTypeSelectionWizardModel which utilizes the functions from the ProcessingTypeProvider to manipulate the UI.

The StandardSetCreationProvider offers the necessary functions for the standard set creation wizard. Since the wizard allows just the creation of new measuring points as-well as new monitors with new measuring points, it is necessary to provide functionality for both choices. The user is presented with every model element from the workspace and can choose to create a new standard set entity for every model. Utilizing Parsley we create a monitor <-> measuring point pair for every model element, only saving those pairs, that the user selects through check-boxes. Since our extension point schema knows which metric descriptions are suggested for which measuring point, the metric descriptions, along with the default processing type FeedThrough, is added to the monitor.

Wizardmodel Package

In the Wizardmodel we combine common functionality for the wizard and its pages. The WizardModelManager manages the data necessary for the whole wizard process. He gets called before opening the wizard and provides the Monitor we will work with throughout the wizard. If the user is creating a new measurement, a monitor will be created for this purpose, otherwise the monitor to edit will be hand over. We work with the Monitor, because we get access to the MeasuringPoint and the MetricDescriptions through him. Furthermore the WizardModelManager provides the finish and cancel functionality of the wizard in which all changes are saved or discarded respectively. In addition he supplies the the wizard pages with their corresponding wizard model. The WizardModel interface defines methods each wizard model has to implement, like the texts of the page an in which cases the finish button is available.

WizardmodelPages Package

The WizardmodelPages package consists of a wizard model for each of the four pages. They all implement the WizardModel interface to implement common methods. Each of them corresponds to their provider in the Dataprovider package. Every wizard model is used in the wizard page to provide it with the necessary data and control as well as execute user interaction.

The MonitorCreationWizardModel provides functionality to edit the name of the monitor and change the activated status.

Through the MeasuringPointSelectionWizardModel the corresponding page gets access to all model elements of the users project. It further handels the cases in which the user has to select up to two additional options for his measuring point. These are managed in the three MeasuringModel objects. The second tab of this page includes unassigned MeasuringPoints which are provided through this class. The creation of the MeasuringPoint matching the user selected model element is likewise implemented in this wizard model.

In the MetricDescriptionSelectionWizardModel the functionality to add and remove MetricDesciptions in all variantions is provided for the third wizard page. We implemented this functionality with two Monitors in two tables where the left one is a dummy monitor the show available MetricDescriptions while the the user created one is on the right. The creation and management of the dummy monitor is handled in this class. If you want to know how we define what Metrics are offered to the user look up the Extension Point. In addition the descriptions for each Metric can be accessed through this wizard model.

The ProcessingTypeSelectionWizard provides the fourth page with the available ProcessingTypes. It specifies which properties each ProcessingType has and offers the functionality to edit these.

Extension Point

In Eclipse Extension Points are used to allow plug-ins to extend or customize parts of its functionality. These plug-ins are then called extensions. For example our Measurments-Dashboard view is an extension of the Eclipse view extension point. Eclipse offers lots of extension points to customize every part of its IDE, like the toolbar, menus, shortcuts etc. This concept can be used in your own projects to provide developers with easy ways to extend your software. You have to define a extension point schema for each extension point, which declares the elements and attributes that extensions to that point must declare. If you are interested in more information about extension points look up:

MeasuringPointMetricsWorkingCombinations Extension Point

For our project we implemented an extension point to define which combinations of Measuring Points and Metric Descriptions work in a SimuLizar simulation run.

By the time of writing there exist over 60 implemented MetricDescriptions, which are bundeled in the MetricDescriptionsConstants. But not all of them are implemented for each type of Measuring Point. In fact most of the time only very few actually work. If you don't know which ones work your only option right now is to find out by trial and error. That's why this extension point is used to define all the working Combinations of Measuring Points and Metric Descriptions. With that information we show users a list of only working MetricDescriptions when they want to decide what he wants to measure for the simulation. In the third page of our wizard, where users have to selcet the MetricDescriptions only extensions to this extension point are shown. Furthermore you can define which of the working Metric Descriptions should be suggested to a user as default measures. This helps newer/not experienced users to start and learn what you can measure in a simulation.

Extension Point Schema

The extension point schema is defined as follows:

ID: an ID to differenciate between extensions
MeasuringPoint: Enum of the 11 currently existent and supported MeasuringPoints. You have to select one of the 11.
MetricDescription: ID of the MetricDescription, like they are defined in the Common Metrics Specification
SuggestedMetricDescription: boolean whether the MetricDescription should be added to the suggested list of MetricDescriptions for the MeasuringPoint.
Name: a meaningful name for the extension.

An example extension with a UsageScenarioMeasuringPoint and the ResponseTime metric, which should be suggested looks like this:

ID: client1
MeasuringPoint: UsageScenarioMeasuringPoint
MetricDescription: _6rYmYs7nEeOX_4BzImuHbA
SuggestedMetricDescription: true
Name: UsageScenarioWithResponseTime

Contributions

To contribute to our extension point you would need to create a plug-in project and import the 'org.palladiosimulator.measurementsui.extensionpoint.definitions' package in the plugin.xml. Afterwards you would switch to the 'Extensions' tab and add our extension point. In the last step you can add new extension by right-clicking on the extension point -> new -> client and complete the extension point schema.

In the package 'org.palladiosimulator.measurementsui.extension.contributions' we implemented some extensions to this extension point. You can excess them the same way, by opening the plugin.xml file and switching to the Extensions tab.

Implementation

To make use of extensions you have to access them in your code. We defined this process in the EvaluateExtensions class. We load the attributes of our schema and create EObjects accordingly. Afterwards we store each combination of MeasuringPoint and MetricDescription in a corresponding Map which is used to calculate the available metrics in the third wizard page. To load extensions in general, you would use something similar to:

public void loadExtensions() {

       IExtensionRegistry registry = Platform.getExtensionRegistry();
		IConfigurationElement[] configurationElements = registry.getConfigurationElementsFor(EXTENSION_POINT_ID);

		for (IConfigurationElement configurationElement : configurationElements) {		 
		    
		    String measuringPointClassname = configurationElement.getAttribute("MeasuringPoint");
		    String metricDescriptionId = configurationElement.getAttribute("MetricDescription");
		    String suggestedMetric = configurationElement.getAttribute("SuggestedMetricDescription");

                   // Create Objects from these attributes and use them in your code
	}
}

Measurements Dashboard View

The Measurements Dashboard relates to the Eclipse view giving the user an overview about all Modelling Projects, MonitorRepositories, Monitors and Measuring Points without a Monitor. Measurements Dashboard is implemented on the Eclipse E4 platform. The view consists out of two parsley tree viewers, the MonitorTreeViewer and the EmptyMeasuringPointsTreeViewer. For more informations about the viewer implementation look at the chapter Parsley in the SimuLizar Usability Extension Project. Furthermore there are additional Buttons and DropDown menus for further functionality. The whole UI is implemented with the eclipse.swt library. The measurement dashboard implementation can be found in the following package:

org.palladiosimulator.measurementsui.measurementsdashboardconsists out of the following sub packages:
org.palladiosimulator.measurementsui.measurementsdashboard.filter provides filtering functionality for both viewers of the dashboard.
org.palladiosimulator.measurementsui.measurementsdashboard.handlers provides behavior of certain eclipse commands like saving, refreshing or undo/redo.
org.palladiosimulator.measurementsui.measurementsdashboard.listeners contains the all listeners connected with the dashboard.
org.palladiosimulator.measurementsui.measurementsdashboard.parts contains all UI parts implemented for the dashboard.
org.palladiosimulator.measurementsui.measurementsdashboard.viewer contains all viewer implementation.

Handlers

Since the measurements dashboard is implemented on the Eclipse E4 platform commands and handlers have to be integrated via the eclipse compability EHandlerService which is injected in the e4 view. The following code snippet shows how the save command and handler is integrated in the eclipse e4 view.

private static final String SAVE_COMMAND = "org.eclipse.ui.file.save";

@Inject
private EHandlerService handlerService;

@Inject
private ECommandService commandService;

@Inject
private MDirtyable dirty;

//Activates the save command for the view
handlerService.activateHandler(SAVE_COMMAND, new SaveHandler());

//Enable the eclipse save button if changes were made
editingDomain.getCommandStack().addCommandStackListener(e -> {
            if (dirty != null) {
                dirty.setDirty(true);
                commandService.getCommand(SAVE_COMMAND).isEnabled();
            }
});

There exists already a preimplemented SaveHandler in the org.eclipse.e4.ui.internal.workbench.handlers package. The SaveHandler specifies was has to be done if the save command is triggered. Unfortunately for other commands like refreshing or undo/redo functionality we had to implement our own handlers which are located in the org.palladiosimulator.measurementsui.measurementsdashboard.handlers package. Unfortunately eclipse e4 does not support to enable the undo and redo button right now. Instead the shortcut Strg + Z, String + Y for windows or Cmd + Z, Shift + Cmd + Z for MacOS has to be used. Additionaly the context menu for the two integrated viewers can be used.

Wizard Component

General

The wizard component contains everything that is related to the Measurement wizards for creating and editing the Measurements. The wizards can be accessed from within the dashboard view (for more details on how to access and use the wizard, see the 'User Guide' section).

All source code related to the wizard is located in the projects within the 'bundles' folder.

The main project for the wizard is:

'org.palladiosimulator.measurementsui.wizard'

Besides that, a number of Parsley projects are used for some of the wizard pages. These are as follows:

'org.palladiosimulator.measurementsui.selectmetricdescriptions.available' (3rd page which is for Metrics selection, for displaying available Metrics)
'org.palladiosimulator.measurementsui.selectmetricdescriptions.selected' (3rd page which is for Metrics selection, for displaying selected Metrics)
'org.palladiosimulator.measurementsui.processingtype' (4th page which is for Processing Type selection, for displaying the selected Metrics along with Processing Types and its attributes)

Used technologies

Parsley

Parsley is one of the technologies that are used for the wizard. It provides different kinds of EMF based UI components which in our case are tables in the 3rd and 4th page, as they are explained in the 'User Guide' section. The advantage with Parsley is that it autarkically manages displayed content. For example the tables in the 3rd page contain available/selected Metrics. You simply have to pass the Monitor object to the Parsley view which then displays the content defined in the DSL file, in this case its Metric Descriptions. This simplifies the management of displayed content, as otherwise you would have to manually add the according table items/rows. You can find more details on how we used Parsley in the 'Parsley' section of the Developer Guide.

JFace Wizard

We used the JFace Wizard framework as a basis for our wizard. It provides basic functions such as 'Back', 'Next', 'Finish' and 'Cancel' buttons, manages the order of the pages, provides programmable info and help functions etc. With its high customizability, it serves as a good foundation for the wizards.

SWT

For custom GUI elements we used the 'Standard Widget Toolkit' (SWT) for Java. These are for example: Drop down menus/comboboxes, textfields, checkboxes, custom buttons, images etc. Also other special GUI functions are implemented with SWT, such as click and key listeners, drag and drop, layouts etc.

General Implementation

The main class for the wizard is org.palladiosimulator.measurementsui.wizard.main.MeasurementsWizard. There, the various wizard pages are created and properties such as the size are set. Also the org.palladiosimulator.measurementsui.wizardmodel.WizardModelManager is initiated, which handles the internal model for all actions that the user performs during the use of the wizard. It is passed to all wizard pages. For more details on the data model please see the 'Data Component' section of the Developer Guide.

Each wizard page works similarly to each other. Firstly, all GUI elements are added such as Parsley views, buttons, textfields, checkboxes etc. Furthermore layouts are set and other GUI functions are added such as editability, listeners, label providers for tables etc. All classes that are related to these GUI functions of the wizard pages are contained in the 'handlers' package of the 'org.palladiosimulator.measurementsui.wizard' project.

Note: In the 3rd page, which is for the selection of Metrics, two tables are used. In this case, 2 different Parsley views with a different Monitor each are used, not one Monitor for both.

Note2: In the 4th page, which is for the selection of Processing Types, we use a separation of displaying and editing the property values. For displaying the current values we use a label provider. For editing the values we use editing support. These handler classes are found in the 'handlers' package. This enables the display of additional information when the data is only displayed, and can be omitted, when editing the values. For a demonstration, feel free to try it!

Note3: Also in the 4th page, you will notice that in the Parsley DSL file we declared the following:

featuresProvider{
	features{
		MeasurementSpecification -> metricDescription, metricDescription, metricDescription, metricDescription
	}
}

Normally, this would add 4 columns with the same content, but we override the last 3 columns with help of the label provider (and also editing support, when editing). This is necessary since we display attributes of the processing type which are not direct attributes of the metric itself. Using Parsley as shown above, even when overriding it, is still preferential as it still simplifies the management of displayed data per row - otherwise we would have to add and manage all table items/rows manually.

UML Sequence Diagram for a Standard Procedure of the Wizard

For a better understanding on how the wizard component works, here we illustrate an exemplary sequence diagram.

The wizard can be opened through multiple ways, as described in previous sections. Here the sequence is described for the standard procedure when the user wants to create a new Measurement by clicking the 'Add new Measurement' button. There are multiple paths possible, e. g. when entering the wizard on a different page or going back to a previous page, but for simplicity these branches are not shown.

When the user clicks the 'Add new Measurement' button, a new org.palladiosimulator.measurementsui.wizard.main.MeasurementsWizard is created. During the creation process also a org.palladiosimulator.measurementsui.wizardmodel.WizardModelManager is created which handles the internal model, as previously described.

(All classes for the wizard pages are located in the 'pages' package of the 'org.palladiosimulator.measurementsui.wizard' project, in the following the package information is omitted.) Beside the internal model, the wizard pages are created and added. Hereby the starting page is the MonitorCreationWizardPage. Here the user can enter the name of the Monitor and set it activated/deactivated with a provided checkbox. As shown in the diagram below, the internal model WizardModelManager calls the respective methods to set the according attributes (e. g. setMonitorName(...) or setMonitorActivated(...)).

When the user presses the 'Next' button, the wizard is continued on the ChooseMeasuringpointWizardPage where he can select a Measuring Point. Again, the respective method of the internal model WizardModelManager is called to set the selected Measuring Point. The next 2 pages work similarly (AdditionalModelsToMeasuringpointWizardPage and FinalModelsToMeasuringpointWizardPage).

When the user reaches the following page, MetricDescriptionSelectionWizardPage, the user can add Metrics and remove them, if necessary. Each time, again, the according methods of the internal model are executed to add and/or remove them.

On the final page, ProcessingTypeSelectionWizardPage, the user can choose a Processing Type and set its attributes, if available. The respective methods of the internal WizardModelManager are called within the EditingSupport classes that are used to edit the table cells of the table.

At the end of the procedure, when the user clicks 'Finish', the WizardModelManager starts the saving process which consists of adding the elements to the repository as specified and saving it.

To summarize: Each time the user performs an action within the GUI of the wizard, the according action is performed by the internal model. This internal action depends on the wizard page and on the kind of action that the user performs. Also the location of the call depends on the context, for example actions that are triggered by buttons are generally executed by according button listeners. Other common actions are often related to tables - in these cases the actions are executed by according EditingSupport or CellModifier classes.

EMF Parsley

EMF Parsley is a framework for easy UI development based on EMF. It comes with a lot of build in functionality, reusable components and it can be quickly customized. Right now there are three components available, trees, forms and tables as well as combinations of those. Parsley projects are defined using a DSL which functions like a modern Java language (streams everywhere). You can use EMF Parsley if you want a basic visualization of an EMF model with a lot of functionality for the user to create and edit data based on that EMF model. For example the current implementation of a MonitorRepository, the editor you get after double-clicking on a '.monitorrepository' file in your project, is a parsley tree in which you can add, delete and edit monitors. This example illustrates many benefits you get from using EMF Parsley:

Visualisation of all elemts of an EMF model: MonitorRepository -> Monitors as children -> Measurement Specification as children
Build in creation of new elements depending on which element is selected: Right-click -> new child/sibling
Context menu with build in undo, redo, cut, copy, paste and delete functions
Drag and Drop
Included in typical Eclipse IDE functionality, like the dirty state and saving mechanic
Integrated into the Eclipse properties view: If you select an element of the Parsley tree you see it with all attributes in the properties view, where it can be edited directly
and more...

You can achieve that by only changing one line in a Parsley project, where you define the location of your '.monitorrepository' file.

To start with Parsley you would either use a Modeling Tools Eclipse version or install it from their website. Afterwards you create a new EMF Parsley Dsl Based Project, select your visualisation type and change the resource URI. You can customize every part of the Parsley view, like the labels, icons, the menus and what to show to begin with. There is a detailed Documentaion of these possibilities.

Parsley in the SimuLizar Usability Extension Project

In order to use Parsley in our Project we integrated viewers build by a Parsley Factory in our view or wizard. For this we used the tutorial to integrate Parsley in an Eclipse e4 plugin given by the Parsley Documentation and integrated it in our own structure. The classes associated with the Parsley View integration are located in the following packages:

'org.palladiosimulator.measurementsui.abstractviewer'
'org.palladiosimulator.simulizar.ui.measurementsdashboard.viewer'
'org.palladiosimulator.measurementsui.wizard.viewer'

The parsley integration is based on various abstract classes implementing different properties as well as classes which are finally creating the parsley viewer. These classes are explained in more detail below.

ComponentViewer: The Component Viewer implements the basic necessary code in order to integrate an parsley view. Note that the attribute EditingDomain isn't necessarily the same EditingDomain which is used by the parsley implemantation because we unfortunately can't influence that. Furthermore we used the following code snippet in order retrieve the EditingDomain of the shown model instead of the code given by the Parsley Documentation because the proposed way caused various bugs.

this.editingDomain = AdapterFactoryEditingDomain.getEditingDomainFor(modelRepository));

SaveableComponentViewer: The SaveableComponentViewer adds implementation to edit data in the viewer and also to save these changes. In order to avoid a bug where we couldn't delete MeasuringPoints after saving we had overwrite the updateResource Method. Somehow setting the editingDomain to null after updating solves this problem. We suspect that this has something to do with parsley using its own editing domain and by setting the editing domain to null there might be parsley internal refresh method triggered. Also, we added a ResourceChangeListener to the EditingDomain in order to update the dirty state of the view where these viewer are used in.

@Override
    protected Resource updateResource(EObject model) {
        resource = super.updateResource(model);
        initResourceChangedListener(editingDomain);
        // For some mysterious reason the editing domain has to be set null here else parsley's
        // context menu won't function anymore if you want to delete a measuring point
        editingDomain = null;
        return resource;
    }

MeasurementsTreeViewer and WizardTableViewer: Both classes are building the JFace Viewer Objects which are shown in the UI with the help of the matching parsley factory. This is done by overwritting the initParsley-Method. If a viewer other than a TreeViewer or TableViewer is required, a similar class must be implemented which adapts the initParsley method. Unfortunately there is only an example for an TreeFormComposite given in the Parsley Documentation. You have to inspect the parsley source code in order to find the right functions creating your desired viewer.
Inheriting classes from MeasurementsTreeViewer and WizardTableViewer: In order to implement a viewer you have inherit from the MeasurementsTreeViewer, WizardTableViewer or your own class implementing a viewer and inheriting from ComponentViewer. All these classes need overwrite the initInjector-Method which sets the parsley google guice injector. This injector can be retrieved by building your own Parsley Project or by using one of the parsley projects included in our implemenation. Additionally methods like for example initDragAndDrop can be overwritten customizing certain behaviour of the viewer.

Problems with EMF Parsley

We use EMF Parsley in different views in the dashboard as well as in the wizard. But we encountered a multitude of problems when you go beyond the simple use case we described in the section previously. In our project we combined Parsley components with other SWT components in one view, which negates a lot of the built in functionality. We integrated the Parsley views into a Eclipse 4.x application, like described int the Eclipse 4.x part of the documentation. After that you have to handle:

The EditingDomain: The Parsley view has its own EditingDomain, which might be a different one from the rest of your application. If you have multiple ways to interact with the EMF models, like we have with buttons that can edit/delete Monitors, you will probably run into problems. This also effects the undo, redo etc. functionality.
The built in drag and drop functionality will probably not work correctly between different view components, thus you have to write it yourself.
The dirty state and save mechanic doesn't work automatically anymore. You will have to implement it yourself, which combined with the EditingDomain problem can cause a lot of unintended functionality.
There is no link to the properties view. You can write your own properties view with a Parsley form view but this is a lot harder then it seems and doesn't work properly, in our experience (might be more of an Eclispe 4 problem).
You can't show multiple different EMF models in one Parsley view, at least we couldn't find out how.

All these problems can be summerized under one: Documentation. There is almost no documentation beyond the Parsley hompage, no elaborate tutorials, forum or stackoverflow entries. If you want to do something outside of the simple use cases it is hard to find anything. That is why we decided to create our own implementations in some cases. Furthermore we customized some Parsley views through the Eclipse SWT framework since you get for example a treeFormComposite Object when using Parsley with Eclipse 4.

Maven Tycho

For build management of this plugin Maven Tycho was used. Maven Tycho is an extension of the standard Maven build system which supports the build process of Eclipse Plug-ins. A good tutorial on the basics and functionality Maven Tycho can be found at Vogella Maven Tycho Tutorial.
Here is a short summary of our build:

Basic Structure

Each folder is dedicated to a certain part of the project. The pom.xml-files define the structure of the project for the build process by specifying the modules each folder contains. The pom.xml in the root folder also sets the path to the configuration pom.xml file which can be found at /releng/org.palladiosimulator.measurementsui.configuration.

Bundles

In the bundles folder you find the actual source code of the project. It is subdivided into several subprojects, of which each has its own encapsulated, defined functionality. Since this is a Tycho build each project does not have a pom.xml file, because the dependencies are derived from the MANIFEST files of each project.

Features

Eclipse-Features should be created inside this folder. Currently there is only an example feature, which only demonstrates how features are defined.

Releng

In the releng-folder (short for Release Engineering) is the aforementioned org.palladiosimulator.measurementsui.configuration folder, which contains the main pom.xml. This pom-file defines the build process for the whole project. In the same folder you can find the Checkstyle rules which were used during the implementation. Another important part of the releng folder is the target-file, which defines the target platform the project was developed against. This target definition is used by Tycho for the build process. When you add new plugins to the dependencies of the project, make sure that these are also included in the target definition.

Tests

In this folder you can find the tests defined for this project. Since this extension is a UI extension, it currently contains several SWTBot tests.

Additional information:
The module definitions within the pom.xml files have to be specified by using the names of the folders and not the name of the projects (normally they are the same, but they may differ).
You can bind the Maven execution to a Sonar server by specifying it in the existing sonar profile within the configuration pom.xml file. You will need to provide a URL, an organization and a login key. More information on this can be found at Sonar integration with maven.
In the same pom.xml file you can specify which Checkstyle rules should be used for the checkstyle execution. Currently the Checkstyle rules from the file within the configuration folder are specified.