Commit 1af4a4d6 authored by Levi Lucio's avatar Levi Lucio
Browse files

refactored FOCUSer documentation to include remarks from Vincent

refs 3039
parent d7bb0d12
......@@ -20,13 +20,19 @@
<h2><font color="#336699">1. Introduction</font></h2>
FOCUSer is a system that allows guiding the modeler through a set of actions in order to build a model. <br /> <br />
It does so by highlighting problems in the model that are pertinent to the current state of development of the model and proposing new modeling objectives based on that same state. <br /> <br />
FOCUSer is non-invasive, is the sense that provides guidance to the user while giving him or her full freedom to select the next modelling actions.
FOCUSer is a system that allows guiding the modeler through a set of actions in order to build a model. It does so by highlighting problems in the model that are pertinent to the current state of development of the model and proposing new modeling objectives based on that same state.<br><br>
<h2><font color="#336699">2. <a href="process_definition.html">Defining your own process</a></font></h2>
The main concepts of the system are <b>constraint</b>, <b>objective</b> and <b>process</b>. <a href="process_constraints.html"><b>Constraints</b></a> are mechanisms that evaluate the state of the model against arbitrary properties and visually report errors or warnings to the IDE when those properties do not hold. An <b>objective</b> is composed of a set of <b>constraints</b>. In order to achieve an objective the modeler has to satisfy all constraints that objective entails. <a href="process_definition.html"><b>Processes</b></a> are composed of <b>objectives</b> that may depend on each other. In order to fulfill a process a modeler has to fulfill all of its objectives. Ideally, the modeler starts with objectives that have no dependencies and progressively fulfills objectives by following the dependency graph.<br><br>
<h2><font color="#336699">3. <a href="process_usage.html">Making use of FOCUSer during model development</a></font></h2>
<img src="./pictures/FOCUSER_do-178c_with_constraints.png" style="max-height: 500px;"><br><br>
In the image above we depict a process (on the left side of the picture) and a set of constraints used by that process (on the right side of the picture). Take for instance the objective "Requirement information is complete". In order to arrive to this objective the modeler will first have to fulfill its dependencies, in this case the "Requirements are defined" objective which implies satisfying the "All requirement packages have at least on requirement" constraint. Then, in order to fulfill the objective itself the fields "name", "ID", "rationale", "description" and "author" of all requirements have to be filled out, as stated by the objective's constraints. After this is done, and the "One aspect is defined for each requirement" objective is also fulfilled, the modeler can proceed to the "Requirements are approved by reviewer" objective.<br><br>
Processes in FOCUSer are descriptive, rather than prescriptive. In practice this means that FOCUSer is non-invasive in the sense that it provides guidance to the user while giving him or her full freedom to select the next modeling actions.
<h2><font color="#336699">2. <a href="process_usage.html">Making use of FOCUSer during model development</a></font></h2>
<h2><font color="#336699">3. <a href="process_definition.html">Defining your own process</a></font></h2>
<h2><font color="#336699">4. <a href="process_constraints.html">List of implemented constraints</a></font></h2>
......
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--
Documentation of FOCUSer - FOCUS procEss AwaReness.
@author lucio
@author $Author$
@version
@ConQAT.Rating
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>FOCUSer - Making an AutoFOCUS3 (AF3) Aware of Modelling Processes</title>
</head>
<body>
<li>The <b>Constraint</b> level: </li><br> Constraints are predicates that convey information about the model. When a constraint is active and evaluates to false, then errors or warnings are displayed in the IDE on top of the visible elements of the model those constraints relate to.<br><br>
A constraint needs to be defined programmatically. As an example we will define a constraint for the AF3 MIRA plugin that defines a software requirements gathering framework. This specific constraint evaluates if all requirements have a name.<br><br>
<ul>
<li> Step 1: Create your constraint as a java file in the <b>Constraint</b> folder in your plugin (you can simply copy, rename and modify a constraint if one exists).
<img src="./pictures/FOCUSER_constraint_plugin.png" style="max-height: 280px;">
<br><br>
<li> Step 2: Write the logic for the <b>verify</b> and the <b>isApplicable</b> methods. The <b>isApplicable</b> method checks for the correct type of model object to evaluate the constraint on. The <b>verify</b> methods contains the logic of the predicate.<br><br>
Note that a constraint class needs to inherit from the <b>AF3ProjectConstraintCheckerBase</b> and the <b>RequirementConstraintsGroup</b> classes.
<img src="./pictures/FOCUSER_constraint_class_definition.png" style="max-height: 300px;">
<br><br>
<li> Step 3: Activate the constraint in the base plugin (in this case MIRA), by adding the new constraint to the activator java class.<br><br>
<img src="./pictures/FOCUSER_activator_constraint.png" style="max-height: 100px;"><p>
<img src="./pictures/FOCUSER_activator_code.png" style="max-height: 100px;">
<br><br>
<li> Step 4: in the corresponding UI plugin (in our example for the MIRA plugin) in the <b>Constraint</b> folder, add the Java class that will manage the appearance of the constraint.<br><br>
<img src="./pictures/FOCUSER_constraint_plugin_ui.png" style="max-height: 180px;"><p>
<img src="./pictures/FOCUSER_constraint_plugin_java_ui.png" style="max-height: 500px;">
<li> Step 5: Activate the constraint in the corresponding UI plugin for MIRA, by adding the new constraint to the activator java class.<br><br>
<img src="./pictures/FOCUSER_constraint_ui_activator.png" style="max-height: 120px;">
</ul>
</body>
</html>
\ No newline at end of file
......@@ -16,50 +16,22 @@
</head>
<body>
<h2><font color="#336699">2. Defining your own process</font></h2>
<h2><font color="#336699">3. Defining your own process</font></h2>
Defining a process using FOCUSer is done at two different levels:
<ul>
<li>The <b>Constraint</b> level: </li><br> Constraints are predicates that convey information about the model. <br /> <br />
When a constraint is active and evaluates to false, then errors or warnings are displayed in the IDE on top of the visible elements of the model those constraints relate to.<br><br>
A constraint needs to be defined programmatically. <br /> <br />
As an example we will define a constraint for the AF3 MIRA plugin that defines a software requirements gathering framework. <br /> <br />
This specific constraint evaluates if all requirements have a name.<br><br>
<ul>
<li> Step 1: Create your constraint as a java file in the <b>Constraint</b> folder in your plugin (you can simply copy, rename and modify a constraint if one exists).
<img src="./pictures/FOCUSER_constraint_plugin.png" style="max-height: 280px;">
<br><br>
<li> Step 2: Write the logic for the <b>verify</b> and the <b>isApplicable</b> methods. The <b>isApplicable</b> method checks for the correct type of model object to evaluate the constraint on. The <b>verify</b> methods contains the logic of the predicate.<br><br>
Note that a constraint class needs to inherit from the <b>AF3ProjectConstraintCheckerBase</b> and the <b>RequirementConstraintsGroup</b> classes.
<img src="./pictures/FOCUSER_constraint_class_definition.png" style="max-height: 300px;">
<br><br>
<li> Step 3: Activate the constraint in the base plugin (in this case MIRA), by adding the new constraint to the activator java class.<br><br>
<img src="./pictures/FOCUSER_activator_constraint.png" style="max-height: 100px;"><p>
<img src="./pictures/FOCUSER_activator_code.png" style="max-height: 100px;">
<br><br>
<li> Step 4: in the corresponding UI plugin (in our example for the MIRA plugin) in the <b>Constraint</b> folder, add the Java class that will manage the appearance of the constraint.<br><br>
<img src="./pictures/FOCUSER_constraint_plugin_ui.png" style="max-height: 180px;"><p>
<img src="./pictures/FOCUSER_constraint_plugin_java_ui.png" style="max-height: 500px;">
<li> Step 5: Activate the constraint in the corresponding UI plugin for MIRA, by adding the new constraint to the activator java class.<br><br>
<img src="./pictures/FOCUSER_constraint_ui_activator.png" style="max-height: 120px;">
</ul>
<br><br>
<li>The <b>Process </b> level: </li> <br> A FOCUSer process is defined in AF3's IDE as a set of objectives that depend on each other. <br /> <br />
Each objective is itself formed by a set of constraints that have been previously defined programmatically, as explained in the text above. <br /><br />
In order to define a process you need to do the following:<br><br>
<li>The <b>Process </b> level: </li> <br> A FOCUSer process is defined in AF3's IDE as a set of objectives that depend on each other. Each objective is itself formed by a set of constraints that have been previously defined programmatically, as explained in the text above. In order to define a process you need to do the following:<br><br>
<ul>
<li> Step 1: In order to create a first objective double-click on your project and edit your constraint on the panel on the right.<br><br>
<img src="./pictures/FOCUSER_create_new_objective.png" style="max-height: 250px;"><br><br>
<li> Step 2: After naming the objective you can then select the constraints that should be active by ticking them off. Note that for the objective to be fulfilled all of its constraints need to be satisfied by the model.<br><br>
<img src="./pictures/FOCUSER_select_constraints_for_objective.png" style="max-height: 400px;"><br><br>
<li> Step 3: Objectives can depend on other objectives, which semantically means that in order for the objective to be fulfilled its dependencies need to be first satisfied.<br><br>
<img src="./pictures/constraints_objective_dependencies.png" style="max-height: 320px;"><br><br>
<img src="./pictures/FOCUSER_constraints_objective_dependencies.png" style="max-height: 320px;"><br><br>
</ul>
<br><br>
<li>The <b>Constraint</b> level: </li><br> Constraints are predicates that convey information about the model. When a constraint is active and evaluates to false, then errors or warnings are displayed in the IDE on top of the visible elements of the model those constraints relate to.<br><br>
A constraint needs to be defined <a href="https://af3-developer.fortiss.org/projects/autofocus3/wiki/Add_a_new_constraint_on_a_metamodel">programmatically</a>.
</ul>
</body>
......@@ -16,58 +16,49 @@
</head>
<body>
<h2><font color="#336699">3. Making use of FOCUSer during model development</font></h2>
<h2><font color="#336699">2. Making use of FOCUSer during model development</font></h2>
The main functionality of FOCUSer is to restrict the error and warning messages to the ones that are relevant to the modeling task at hand. <br /> <br />
This is achieved by guiding the user through the selection and activation of objectives that should be achieved next. <br /> <br />
Note that FOCUSer was built to be non-invasive, in the sense that objective selection is always done by the modeler and is not imposed by the IDE.
The main functionality of FOCUSer is to restrict the error and warning messages to the ones that are relevant to the modeling task at hand. This is achieved by guiding the user through the selection and activation of objectives that should be accomplished next.
<h3><font color="#336699">3.1. Current and upcoming objectives</font></h3>
<h3><font color="#336699">2.1. Current and Upcoming objectives</font></h3>
The AF3 IDE presents to the user two combo boxes that control FOCUSer: the <b>current objective</b> and the <b>upcoming objective</b>.<br><br>
The AF3 IDE presents to the user the two combo boxes that allow making use of FOCUSer: the <b>current objective</b> and the <b>upcoming objective</b>.<br><br>
<img src="./pictures/FOCUSER_current_upcoming_objective.png" style="max-height: 170px;"><br><br>
<ul>
<li> <b>Current objective: </b> the current objective box displays which objective is currently set, which in turns activates all the constraints related to that objective. As a result, all errors and warnings related to those constraints will appear in the IDE (but no others). Note that constraints implied by objectives transitively found in the dependency chain are also activated.<br><br>
<li> <b>Current objective: </b> the current objective box displays which objective is currently set, which in turns activates all the constraints related to that objective. As a result, all errors and warnings related to those constraints will appear in the IDE (but no others). By using this box the modeler can set any objective in the process at any time and make it the current objective. Note that constraints implied by objectives transitively found in the dependency tree of the current objective are also activated.<br><br>
<li> <b>Upcoming objective: </b> the upcoming objective box displays which objectives are upcoming, given the ones that were already fulfilled.<br><br>
<li> <b>Upcoming objective: </b> the upcoming objective box displays which objectives should be accomplished next, given the ones that were already fulfilled.<br>
</ul>
<h3><font color="#336699">3.2. Using the process as a modeling aid</font></h3>
<h3><font color="#336699">2.2. Using the process as a modeling aid</font></h3>
In order to demonstrate the capabilities of FOCUSer we will build a partial project for aiding the modeler in building requirements using AF3's MIRA framework. <br /> <br />
The process includes three objectives that depend on each other as indicated by the arrows in the following figure. <br /> <br />
In the figure the direction of the arrows defines the direction of the dependencies.<br><br>
In order to demonstrate the capabilities of FOCUSer we will build a partial project for aiding the modeler in building requirements using AF3's MIRA framework. The process includes three objectives that depend on each other as indicated by the arrows in the following figure. In the figure the direction of the arrows defines the direction of the dependencies.<br><br>
<img src="./pictures/FOCUSER_requirements_process.png" style="max-height: 350px;"><br><br>
Note that an (empty) default configuration is always present in the project. <br /> <br />
In our process in the figure above the default configuration corresponds to the <i>"At least one requirement exists"</i> constraint.<br><br>
Note that an (empty) default configuration is always present in the project. In our process in the figure above the default configuration corresponds to the <i>"At least one requirement exists"</i> constraint.<br><br>
Once the modeler starts a building a requirements model, the color of the current objective box is set to the color red. <br /> <br />
This indicates the objective is not yet been satisfied.<br><br>
Once the modeler starts a building a requirements model, the color of the current objective box is set to the color red. This indicates the objective has not yet been satisfied.<br><br>
<img src="./pictures/FOCUSER_default_configuration.png" style="max-height: 200px;"><br><br><br>
The modeler can then right-click on the error message to understand what the current required modeling actions are that will lead to fulfilling the active constraints.<br><br>
<img src="./pictures/FOCUSER_constraint_message.png" style="max-height: 200px;"><br><br><br>
<img src="./pictures/FOCUSER_constraint_message.png" style="max-height: 240px;"><br><br><br>
Once a requirement has been added the color of the current objective is set to green and the upcoming objective is set to the one(s) that depend on it (in this case that all requirements should have a name).<br><br>
<img src="./pictures/FOCUSER_default_configuration_OK.png" style="max-height: 200px;"><br><br><br>
<img src="./pictures/FOCUSER_default_configuration_OK.png" style="max-height: 180px;"><br><br><br>
The modeler can then turn the upcoming objective into the current objective by selecting it from the combo box.<br><br>
<img src="./pictures/FOCUSER_select_upcoming_objective.png" style="max-height: 200px;"><br><br><br>
<img src="./pictures/FOCUSER_select_upcoming_objective.png" style="max-height: 180px;"><br><br><br>
Note that it is possible for the modeler to understand which percentage of the objective at hand is already complete. <br /> <br />
This is achieved by hovering the mouse on the "current objective" combo box. <br /> <br />
The percentage is calculated in terms of the number of instances of the constraints that currently exist in the project. <br /> <br />
Note that for example for the "All requirements have a name" constraint, one instance of it will exist per requirement in the project.<br><br>
Note that it is possible for the modeler to understand which percentage of the objective at hand is already complete. This is achieved by hovering the mouse on the "current objective" combo box. The percentage is calculated in terms of the number of instances of the constraints that currently exist in the project. Note that for example for the "All requirements have a name" constraint, one instance of it will exist per requirement in the project.<br><br>
<img src="./pictures/FOCUSER_percentage_complete.png" style="max-height: 300px;"><br><br><br>
<img src="./pictures/FOCUSER_percentage_complete.png" style="max-height: 260px;"><br><br><br>
</body>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment