Getting Started with S2A

[12/2007; under construction]

 

Summary

This page provides basic technical guidance on how to get started with S2A. Email the authors for additional information.

Shahar Maoz, Asaf Kleinbort
December, 2007

  

Prerequisites

  1. IBM RSA 7.0 installed (any UML2 compliant editor will work; however the instructions below refer to the RSA environment).
  2. AspectJ installed.
  3. Modal profile: the profile file msdprofileV4.0.profile.uml should be located in c:\msdProfiles.
  4. S2A: two options
    1. External tool: download and extract musdc.zip and musdrt.zip.
    2. Open project: ask for the latest Eclipse projects from the authors. You will need the jars listed in the MANIFEST.MF of the MUSDCompiler project in order to build the compiler. Check the variables in the project properties Java build path libraries.

Setting up the S2A compiler as an Eclipse external tool

  1. Choose Eclipse External Tools new program.
  2. Location should point to the msdc.cmd file (from the extracted folder of musdc.zip). For example: c:\musdc\musdc.cmd.
  3. Working directory should point to the musdc extracted folder. For example: c:\musdc.

Environment settings


Editing a Model: Basics

Creating a new model

Follow the steps below in RSA.
  1. Move to “modeling” perspective.
  2. Create a new “UML Project”. You might want to give the model a name (e.g., “Tutorial”).
  3. In the model’s properties tab choose the profiles tab and “Add Profile”. In the select profile window choose the file option, browse to c:\msdProfiles folder and select the msdprofileV4.0.profile.uml file (this will add the “modal” profile to the list of applied profiles).

Adding a new sequence diagram

  1. From the model context menu choose Add Diagram / Sequence Diagram. A new UML collaboration and within it a new interaction and within it a new sequence diagram are created. Give the created elements appropriate names. Typically, the interaction and its sequence diagram have equal names.
  2. Remark: to add another diagram inside an existing collaboration choose Add Diagram / Sequence Diagram from the existing collaboration context menu.
  3. Remark: The compiler uses the interactions’ names. Use simple names: no spaces etc.

Editing a sequence diagram

Lifelines
  1. Drag a lifeline from the Sequence Palette. Choose one of the following options:
    1. Create Actor (typically used for lifelines representing a human user and is marked with LifeLineModes / isEnvironment True).
    2. Create Class (to create a lifeline representing a class not yet defined in the model). The name of the class must match your Java class name. In general, to avoid unnecessary problems, we suggest following Java naming conventions.
    3. Select Existing Element (to refer to existing elements from the model: choose an existing class).
  2. Remark: to add a lifeline referencing an existing model element, you can simply drag it.
  3. In the Properties / Advance tab of the lifeline select its modalities.
    1. “Environment” is True if the lifeline represents a non specified participant (user, environment in general). Default is False. Environment lifelines can only be used as source of monitored messages. They can be synchronized using conditions.
    2. “System” is True if the lifeline represents a concrete objects whose binding must be handled by the MSDEnv class (see below). Default is False.
Messages
  1. Choose Synchronous Message from the palette and drag it to the main screen.
  2. Remark: RSA may create a return message and execution occurrence specification. Both are ignored (!) by S2A and can be deleted.
  3. The operation name must match the method name on the target lifeline.
  4. In the Properties / Advance tab of the message select its modalities: execution and temperature. The message may be colored through the properties in its Appearance tab. The same applies to other constructs (see below).
Conditions

RSA 7.0 does not fully support the syntax of UML2. Specifically, state invariants are not supported. S2A supports state invariants which one can add manually in the UML2 open source editor. Alternatively, as a workaround, S2A abuses the Assert Combined Fragment Interaction Constraint as a syntactic construct representing a condition.

  1. Choose the Assert Combined Fragment from the palette and drag it to the main screen.
  2. Choose the lifelines to cover.
  3. The value of the fragment’s Interaction Constraint should hold the condition (written as a Boolean Java expression).
  4. Set the temperature mode of the combined fragment in Properties / Advanced tab (execution mode is ignored).
  5. Remark: typically we hide the “assert” subtitle from the fragment by setting the fragment’s Format / Font size to 0. Also, one may color the fragment’s border in the Appearance tab.

Compiling a Model

Exporting and preparing the model for compilation:
  1. Choose Export / UML Model from the context menu of the model.
  2. Choose the source model (the .emx file)
  3. Choose the destination folder.
  4. A .uml file with the models name is created in the destination folder. This file is used as input to the S2A compiler (can be edited manually if necessary).
  5. Remark: typically, we set the destination folder to the root of the corresponding Java project.
  6. Remark: the musdmodel.properties file must reside in the same destination folder.
Remark: Set the model property in the properties file musdcompiler.properties to point to the full path to the model file (do not add the .uml extension). In external tool mode, this file resides in the extracted folder. In the open projects mode, it resides in the root folder of the project.

In external tool mode, run the external tool.
In open projects mode, run the MUSDCompiler project.

Running an S2A program

For instructions see the installation guide on the S2A website.

Editing a Model: Additional Features

Parameters

A message with arguments must correspond to an operation with the same name and arguments types. To add arguments to an operation, select the operation in the model tree. In the parameters tab select Add New Parameter. Give the parameter any name (it is the formal parameter name, not the actual one). Give the parameter a type:
1. Choose a type from the imported libraries / UML primitive types, OR
2. Choose a type from the model (create one first if you need it, e.g., for 'Event').

Select the message and click the Property Pagesicon (top right of properties pane).
Work under Arguments.

For a symbolic parameter of any type, choose Instance Value.
Give the argument a name (e.g., e for Event, x for int, etc.).
Give the argument a type:
1. Choose a type from the imported libraries / UML primitive types, OR
2. Choose a type from the model (create one first if you need it, e.g., for 'Event').
For exact parameters (concrete, constant) choose Literal X (for X in Integer, String, or Boolean). Give the argument a name, type, and value.

For opaque parameters choose Opaque Expression. Give the argument a name and a type. Use the Body field to add the code (for example: "x == myButton.getProp1(3)", "lifeLineName" to use a lifeline reference as a value for a parameter).

Create messages

Drag a Create Message from the palette. A name must by given although the compiler ignores the specific name used. Typically, we use the name “new()”. Parameters can be added as usual (only in the message itself).

System lifelines

Binding of concrete lifelines (with “System” mode set to True) must be handled by a class name MSDEnv. The class should be imported by the generated code, hence, its location needs to appear in musdmodel.properties file imports property.

MSDEnv must implement the static method Object getLifeLineInstance(String s). The method returns the appropriate object reference. See the examples in the S2A case studies.

Combined fragments: alt, loop

ALT
Drag an Alt Interaction Fragment from the pallet to the main screen. Choose the covered lifelines. For the guards: choose the Interaction Constraint and enter the value (e.g., "x==3") under the General tab.

LOOP
Drag a Loop Interaction Fragment from the pallet to the main screen. Choose the covered lifelines. For the guard:

1. For constant loop, choose the interaction constraint and enter minimum value in the general tab.
2. For an unbounded loop, choose the interaction constraint. Under the Advanced tab choose Specification / Create New Opaque Expression. Enter the expression in the Body field.

Object composition

RSA 7.0 does not support part-decomposition. We thus edit part-decomposition related data directly on the UML2 model.

Prepare all interactions in the tree as usual in RSA. Export the model and open the .uml file using the Eclipse UML Editor. For each decomposed lifeline (parent):

1. Select the parent interaction
2. From the context menu choose New Child / Fragment Part Decomposition
3. Give the new part decomposition a name
4. Point the Refers To field to the part interaction
5. Select the parent lifeline
6. In the Decomposed As field, select the corresponding Part Decomposition