Commit 958d13b1 authored by Pietro Braghieri's avatar Pietro Braghieri
Browse files

Merge branch '12-documentation-improvement' into 'master'

Resolve "Documentation Improvement"

Closes #12

See merge request !12
parents 5e1dd71e f728b155
Pipeline #140891 failed with stages
in 9 minutes and 1 second
# OSLC
[OSLC](https://open-services.net/) (Open Services for Lifecycle Collaboration) is a set of specifications that enable integration of software development. It is based on several web standards, like the W3C Resource Description Framework (RDF), Linked Data and REST and enables integration at data level via links between related resources. OSLC resources are defined in terms of RDF properties. Operations on resources are performed using HTTP.
OSLC is organized into individual topics such a change management, test management, requirements management and configuration management.
These topics have [specifications](https://open-services.net/specifications/) called **domains** which leverage the OASIS OSLC lifecycle integration Core Specification and enable interoperation through the specification of standard domain vocabularies, constraints, and services.
For the integration with our tools, we select the [Automation](https://archive.open-services.net/wiki/automation/OSLC-Automation-Specification-Version-2.1/index.html) specifications.
The OSLC Automation domain define resources as `Automation Plan`, `Automation Request` and `Automation Result`; they are in relationship as shown below
[<img src="/docs/AutomationResourcesRelationship.png" width="600">](/docs/AutomationResourcesRelationship.png)
A OSLC Service Provider based on the OSLC Automation domain has been realized.
The figure below shows the interactions between the OSCL Client ([CHESS](https://projects.eclipse.org/projects/polarsys.chess) in this example) and the Service Provider:
[<img src="/docs/OSLC_FBK_Tool_Interactions.png" width="600">](/docs/OSLC_FBK_Tool_Interactions.png)
The integration and implementation of the tool chain through OSLC is realized by a web application server (i.e. [Tomcat](https://tomcat.apache.org/)) that runs the OSCL Registry (that lists the available services) and the OSLC Service Provider that interacts with the analysis tools as shown below:
[<img src="/docs/OSLC_FBK_Tool_WebApplication.png" width="600">](/docs/OSLC_FBK_Tool_WebApplication.png)
The analysis tool functionalities are be available by means of Automation Plans; the title attribute `<dcterms:title>` of the Automation Plan selects the tool functionality.
At the current time, the available Plans for the FBK analysis tools are the following:
| Analysis Tool Functionality | Automation Plan `dcterms:title` |
| ------ | ------ |
| Check Contract Refinement | ocra_check_refinement |
| Check Contract Implementation | ocra_check_implementation |
| Check Contract Composite Implementation | ocra_check_composite_impl |
| Check Contract Validation Property | ocra_check_validation_prop |
| Compute Fault Tree | ocra_compute_fault_tree |
| Print System Implementation | ocra_print_system_implementation |
| Print Implementation Template | ocra_print_implementation_template |
| Instantiate Parametric Architecture | ocra_instantiate_parametric_arch |
| Get Required Architecture Parameters | ocra_get_required_arch_parameters |
| Behavior Model Check | nuxmv_check_model |
| Expand Fault Extensions | xsap_expand_fault_extensions |
| Extend Model | xsap_extend_model |
| Compute Fault Tree | xsap_compute_fault_tree |
| Compute FMEA Table | xsap_compute_fmea_table|
The OSLC Service Provider exposes additional services for listing the service provider catalogue, the list of Automation Plans that are available in the current instance of service provider, the Automation Requests that were submitted and the list of Automation Results.
Each services has an end point that is listed in the following table:
| Service | End Point |
| ---- | ---- |
| OSLC Service Catalogue | `<web_server_address>/oslc4j-registry/catalog` |
| List of available Plans | `<web_server_address>/<context>/services/autoPlans` |
| List of Current Requests | `<web_server_address>/<context>/services/autoRequests` |
| List of Current Results | `<web_server_address>/<context>/services/autoResults` |
For example, to get the list the available Automation Plans, calls the end point `<web_server_address>/<context>/services/autoPlans` and the corresponding answer will be a RDF/XML output that lists all Automation Plans that are supported by the Service Provider.
---
#### Extend an existing Automation Plan
Suppose you want to extend an analysis tool function by adding a new parameter.
For example, we need to add the parameter `wholeArchitecture` of type `boolean` to the function `Check Contract Validation Property`.
We have to work on both the client side and the server side following these steps:
##### Client Side
Suppose that the `wholeArchitecture` attribute is already present in the class `eu.fbk.tools.adapter.ocra.CheckValidationProperty.java`.
* Add `String PARAM_WHOLE_ARCHITECTURE = "wholeArchitecture"` to the class `eu.fbk.tools.adapter.ToolParameterConstants.java`
* Insert the following fragment in the `getParameters()` method of the class `CheckValidationProperty`
```
if( wholeArchitecture != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_WHOLE_ARCHITECTURE, wholeArchitecture.toString()));
}
```
* Insert the following fragment in the `setParameters(ToolFunctionParameter parameter)` method of the class `CheckValidationProperty`
```
case ToolParameterConstants.PARAM_WHOLE_ARCHITECTURE:
wholeArchitecture = Boolean.valueOf(parameter.value);
break;
```
In the case of parameter that represents a file (i.e. full file path name), we have to convert it into a URI.
The fragment to insert in the `getParameters()` method will be:
```
URI behaviourModel;
...
if( behaviourModel != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_BEHAVIOUR_MODEL, behaviourModel.toString(), true));
}
```
and the fragment to insert in the `setParameters(ToolFunctionParameter parameter)` method will be:
```
case ToolParameterConstants.PARAM_BEHAVIOUR_MODEL:
try
{
behaviourModel = new URI(parameter.value);
}
catch (URISyntaxException e)
{
logger.error("Invalid " + parameter.name +": " + parameter.value == null ? "null value" : parameter.value);
}
break;
```
##### Server Side
We have to modify the plugin [eu.fbk.tools.oslc.provider](/bundles/eu.fbk.tools.oslc.provider) as follow:
* add the following method in the class `eu.fbk.tools.oslc.automation.resources.PlanCatalog.java`
```
private static Property getWholeArchitectureProperty()
{
final Property property = new Property();
property.setName(ToolParameterConstants.PARAM_WHOLE_ARCHITECTURE);
property.setTitle("Whole Architecture");
property.setValueType(ValueType.String);
property.setDescription("If set, compute whole architecture");
property.setOccurs(Occurs.ZeroOrOne);
return property;
}
```
* add the invocation of such method in the `getContractPropertyValidationPlan()` method:
```
public static AutomationPlan getContractPropertyValidationPlan()
{
final AutomationPlan plan = new AutomationPlan();
plan.setIdentifier(CheckValidationProperty.FUNCTION_NAME);
plan.setTitle(CheckValidationProperty.FUNCTION_NAME);
plan.setDescription(CheckValidationProperty.DESCRIPTION);
plan.addParameterDefinition(getTimeoutProperty());
plan.addParameterDefinition(getAsynchronousExecutionProperty());
plan.addParameterDefinition(getContractModelProperty());
plan.addParameterDefinition(getComponentNameProperty());
plan.addParameterDefinition(getTimeModelProperty());
plan.addParameterDefinition(getPropertyValidationType());
plan.addParameterDefinition(getOcraAlgorithmTypeProperty());
plan.addParameterDefinition(getPropertyNameProperty());
plan.addParameterDefinition(getPropertiesProperty());
plan.addParameterDefinition(getPossibilityProperty());
plan.addParameterDefinition(getWholeArchitectureProperty());
try
{
new AutomationPlanResource().createResourceInternal(plan);
}
catch (URISyntaxException e)
{
logger.error(e.getMessage());
}
return plan;
}
```
#### Add a new Automation Plan
Suppose we have already defined a new function (e.g. `CheckValidationProperty`) and we want to implement the remote version.
We have to work on both the client side and the server side following these steps:
##### Client Side
As described in the previous case, we need to implement the `getParameters()` and `setParameters()` methods, according to the function parameters.
```
@Override
public List<ToolFunctionParameter> getParameters()
{
final List<ToolFunctionParameter> parameters = super.getParameters();
if( componentName != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_COMPONENT_NAME, componentName));
}
if( wholeArchitecture != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_WHOLE_ARCHITECTURE, wholeArchitecture.toString()));
}
if( propertyValidationType != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_PROPERTY_VALIDATION_TYPE, propertyValidationType.toString()));
}
if( propertyName != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_PROPERTY_NAME, propertyName));
}
if( properties != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_PROPERTIES, properties));
}
if( possibility != null)
{
parameters.add(new ToolFunctionParameter(ToolParameterConstants.PARAM_POSSIBILITY, possibility));
}
return parameters;
}
@Override
protected void setParameter(ToolFunctionParameter parameter)
{
switch( parameter.name )
{
case ToolParameterConstants.PARAM_COMPONENT_NAME:
componentName = parameter.value;
break;
case ToolParameterConstants.PARAM_WHOLE_ARCHITECTURE:
wholeArchitecture = Boolean.valueOf(parameter.value);
break;
case ToolParameterConstants.PARAM_PROPERTY_VALIDATION_TYPE:
try
{
propertyValidationType = PropertyValidationType.valueOf(parameter.value);
}
catch (Exception e)
{
logger.error("Invalid " + parameter.name +": " + parameter.value == null ? "null value" : parameter.value);
}
break;
case ToolParameterConstants.PARAM_PROPERTY_NAME:
propertyName = parameter.value;
break;
case ToolParameterConstants.PARAM_PROPERTIES:
properties = parameter.value;
break;
case ToolParameterConstants.PARAM_POSSIBILITY:
possibility = parameter.value;
break;
default:
super.setParameter(parameter);
break;
}
}
```
##### Server Side
Also here, we have to modify the plugin [eu.fbk.tools.oslc.provider](/bundles/eu.fbk.tools.oslc.provider)
_New AutomationPlan definition_
* add the following methods in the class `eu.fbk.tools.oslc.automation.resources.PlanCatalog.java`
```
public static AutomationPlan getContractPropertyValidationPlan()
{
final AutomationPlan plan = new AutomationPlan();
plan.setIdentifier(CheckValidationProperty.FUNCTION_NAME);
plan.setTitle(CheckValidationProperty.FUNCTION_NAME);
plan.setDescription(CheckValidationProperty.DESCRIPTION);
plan.addParameterDefinition(getTimeoutProperty());
plan.addParameterDefinition(getAsynchronousExecutionProperty());
plan.addParameterDefinition(getContractModelProperty());
plan.addParameterDefinition(getComponentNameProperty());
plan.addParameterDefinition(getTimeModelProperty());
plan.addParameterDefinition(getPropertyValidationType());
plan.addParameterDefinition(getOcraAlgorithmTypeProperty());
plan.addParameterDefinition(getPropertyNameProperty());
plan.addParameterDefinition(getWholeArchitectureProperty());
plan.addParameterDefinition(getPropertiesProperty());
plan.addParameterDefinition(getPossibilityProperty());
try
{
new AutomationPlanResource().createResourceInternal(plan);
}
catch (URISyntaxException e)
{
logger.error(e.getMessage());
}
return plan;
}
```
* add the `getXXX()` methods if missing (i.e. `getPropertyValidationType()` and `getPossibilityProperty()`)
_New AutomationPlan registration_
* add the new plan in the `eu.fbk.tools.oslc.automation.servlet.ServletListener.java` class
```
Persistence.addResource(PlanCatalog.getContractPropertyValidationPlan());
```
_New AutomationPlan invocation_
* add the invocation of the corresponding function and runner in the `eu.fbk.tools.oslc.automation.resources.AutomationResultResource.java` class
```
switch( autoPlan.getTitle() )
{
case CheckValidationProperty.FUNCTION_NAME:
runner = new OcraRunner(RunnerUtils.getOcraExecutable());
toolFunction = new CheckValidationProperty();
break;
```
#### Web Server Installation
The OSLC Service Provider is tested on [Tomcat](https://tomcat.apache.org/) Web Application Server version 9. There are newer versions but we don't think there are any problems using them.
Following are described two installations, the first is local (_development_ environment) and is used for test purposes in the development phase. The second (_production_ environment) is already in place and runs on the server. They respond respectively to requests to URLs https://localhost:8080/ and https://oslc-es-tools.fbk.eu/.
##### Development (local)
* Edit the `catalina.sh` script (which is located in the `bin` directory of Tomcat installation) and append the following variables at the beginning of file (soon after the initial comment section):
```
...
# LOGGING_MANAGER (Optional) Override Tomcat's logging manager
# Example (all one line)
# LOGGING_MANAGER="-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
# -----------------------------------------------------------------------------
TOOLS4OSLC_DIR=<full path directory where are ES Tools>
JAVA_OPTS="-Xms128m -Xmx1024m -XX:MaxPermSize=256m"
JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.lyo.oslc4j.client.registryuri=http://localhost:8080/oslc4j-registry/catalog/singleton -Dorg.eclipse.lyo.oslc4j.client.uiuri=http://localhost:8080/OSLC4JUI"
JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.lyo.oslc4j.core.servlet.scheme=http -Dorg.eclipse.lyo.oslc4j.core.servlet.hostname=localhost -Dorg.eclipse.lyo.oslc4j.core.servlet.port=8080"
JAVA_OPTS="$JAVA_OPTS -Deu.fbk.tools.oslc.automation.servlet.scheme=http -Deu.fbk.tools.oslc.automation.servlet.hostname=localhost -Deu.fbk.tools.oslc.automation.servlet.port=8080"
JAVA_OPTS="$JAVA_OPTS -Deu.fbk.verification.tool.nuxmv=$TOOLS4OSLC_DIR/nuXmv_linux64"
JAVA_OPTS="$JAVA_OPTS -Deu.fbk.verification.tool.ocra=$TOOLS4OSLC_DIR/ocra_linux64"
JAVA_OPTS="$JAVA_OPTS -Deu.fbk.verification.tool.xsap=$TOOLS4OSLC_DIR/xSAP_linux64 -Deu.fbk.verification.tool.fei_expander=$TOOLS4OSLC_DIR/xsap_functions/bin/expand_fei"
JAVA_OPTS="$JAVA_OPTS -Deu.fbk.verification.tool.mathsat=$TOOLS4OSLC_DIR/mathsat_linux64"
```
* set the tomcat port to `8080` (see the `conf/server.xml` file)
* edit the `conf/tomcat-users.xml` file to create the tomcat `admin` user
```
<role rolename="manager-gui"/>
<role rolename="manager_script"/>
<user username="admin" password="admin" roles="manager-gui, manager-script"/>
</tomcat-users>
```
* copy the ES tools in the `$TOOLS4OSLC_DIR`
* start Tomcat
* install/update the OSLC Service Provider via maven `mvn clean install -P <EclipseVersion>,<JavaVersion>,IntegrationEnvironment`
##### Production (remote)
* the production web server is already in place at `esuser@hubcap-oslc-es-tools.fbk.eu`
* the configuration file: `/data/tomcat/instance1/bin/setenv.sh`. Here are set the environment variables.
* the es tools location: `/home/esuser/tools`
* to start tomcat: `sudo systemctl start tomcat-instance1`
* the admin url is: `https://oslc-es-tools.fbk.eu/manager/text`
* install/update the OSLC Service Provider via maven `mvn clean install -P <EclipseVersion>,<JavaVersion>,PublicEnvironment`
# EATA (Eclipse Analysis Tool Adapters)
EATA Project provides a set of Java [Adapters](/bundles/eu.fbk.tools.adapter.core) to the FBK Analysis tools. Each adapter exposes a set of
functions which map (not exhaustively) some functions of the analysys tools.
Following some class diagrams that present the available functions, grouped by tool.
* **OCRA**
* [Functions Class Diagram 1](docs/ocra_cmds_1.png) [Functions Class Diagram 2](docs/ocra_cmds_2.png)
* **nuXmv**
* [Functions Class Diagram](docs/nuxmv_cmds.png)
* **xSAP**
* [Functions Class Diagram](docs/xsap_cmds.png)
* **Kratos**
* [Functions Class Diagram](docs/kratos_cmds.png)
* **mathsat**
* [Functions Class Diagram](docs/mathsat_cmds.png)
* **ic3ia**
* [Functions Class Diagram](docs/ic3ia_cmds.png)
* **other**
* [Functions Class Diagram](docs/script_cmds.png)
The execution of the function is in charge to the Runner; each tool has its own Runner which implements the specific invocation of the tool executable and the function (see the [Tool Runners Class Diagram](docs/tool_runners.png)). These Runners call the analysys tools locally via `Runtime.getRuntime().exec(..)`. The call is synchronous with the option to specify a timeout.
The result returned by each tool is processed by the ResultBuilder.
There can be a specific ResultBuilder for a given tool; currently only OCRA, nuXmv and XSAP have their own ResultBuilder.
In addition to the tool adapters, EATA project has a [User Interface](/bundles/eu.fbk.tools.adapter.ui) plugin based on the Eclipse plugins `org.eclipse.swt, org.eclipse.jface, org.eclipse.ui`.
The UI plugin allows to invoke the tools functionalities as Eclipse commands. The commands and their parameters are defined in the [plugin.xml](/bundles/eu.fbk.tools.adapter.ui/plugin.xml) file.
Furthermore, there are some result viewers (contract analysys trace, model checking trace, fault tree, fmea table) and a simple manager of the execution requests (`RequestView` class).
---
### OSLC
Let's go back to the Adapter. In addition to the local invocation of the analysis tools, there is also the possibility to interact remotely with the analysis tools through the use of OSLC specifications (or better, an implementation of OSLC for Java, namely [Lyo](https://www.eclipse.org/lyo/)).
For details, please read [this](/OSLC_README.md).
---
### Dependencies
Currently EATA has been tested for Eclipse `Neon`, `2020-06` and `2021-03`
|| Neon | 2020-06 | 2021-03 |
| ------ | ------ | ------ | -----|
| **Java** | 8 | 8 and 11 | 11 |
| **Lyo** | 2.2.0 | 2.2.0 | 2.2.0 |
#### Project Build instruction:
EATA can be build for Eclipse `Neon`, `2020-06` and `2021-03` using Maven.
To select the desired Eclipse version, please use the corresponding Maven profile, respectively: `Neon`, `2020-06` and `2021-03`.
To select the desired Java version, set the maven profile to `Java8` or `Java11`.
**Note:** the project build requires `JDK` version
- checkout the project
- from the terminal
- in case of `Neon`, from the root of the project run: `mvn clean install -Dhttps.protocols=TLSv1.2 -P Neon,Java8` (maven 3.x must be already installed)
- in case of `2020-06`, from the root of the project run: `mvn clean install -Dhttps.protocols=TLSv1.2 -P 2020-06,<Java8|Java11>`
- in case of `2021-03`, from the root of the project run: `mvn clean install -Dhttps.protocols=TLSv1.2 -P 2021,Java11`
- to update the Eclipse workspace:
- activate the target platform corresponding to the Eclipse version
- select all projects `Edit->Select all` and run `Maven->Update Project` from the context menu of the Package Explorer view
#### Update Site Deployment instruction:
It is possible to deploy the EATA plugins on the FBK Update Site (accessible by everyone) by specifying the `deploy` maven phase.
There are actually two updated sites, the Development Update Site and the Production Update Site.
The first one (_Development_) should be aligned with the master source code and is used typically by the developers for integration activities.
The second one (_Production_) is not necessarily aligned with the master but it is an official release of SDE.
As mentioned above, it is possible automatically (via Maven) to build locally the update site of EATA and then copying it to the Update Site server.
Because of the Update Site server is writable only from the FBK local network, this activity must be executed from the FBK local network (or in the FBK VPN).
Also here, the maven command uses Profiles to set the target update site.
So, from the root of the project run:
- `mvn clean deploy -Dhttps.protocols=TLSv1.2 -P Neon,Java8,<DevelopmentUpdateSite|ProductionUpdateSite>`
- `mvn clean deploy -Dhttps.protocols=TLSv1.2 -P 2020-06,<Java8|Java11>,<DevelopmentUpdateSite|ProductionUpdateSite>`
- `mvn clean deploy -Dhttps.protocols=TLSv1.2 -P 2021,Java11,<DevelopmentUpdateSite|ProductionUpdateSite>`
##### Some notes on the EATA update sites
The following information refers to the current update site server installation but it may change in the future, so these notes should be kept up to date.
Server Name: `es-services-website.fbk.eu`
User: `esuser`
The `ssh private key` of the `esuser` must be already present in the machine that runs the maven command.
The repositories of the EATA update site are located in:
`/data/www/es-static.fbk.eu/html/tools/eclipse/<neon|2020-06|2021-03>/<eata|eata_devel>`
The `/data/www/es-static.fbk.eu/html/tools/eclipse/<neon|2020-06|2021-03>/<eata_prev|eata_devel_prev>` hold the very last previous uploads.
They are created/updated automatically at the end of each successful upload of a new update site.
#### The CI/CD
It is automatically activated soon after a push on the master. It runs in a `docker Gitlab runner` on `cerbero.fbk.eu`.
Currently builds the code and creates the update site repository for all versions.
In case of success of those two steps, automatically deploys the _Development_ update site to the server.
Concerning the Production Update site, in the [pipeline](https://gitlab.fbk.eu/ESProjects/EATA/-/pipelines) is available a manual activity (_manual_to_production_update_site_) that deploys the _Production_ update site on the server.
Markdown is supported
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