Title Bar

FLAME User Guide

This FLAME user guide will take you through a set of steps necessary to try FLAME for a collaborative design environment that uses XTEAM. The XTEAM design environment used in this user guide estimates (1) memory usage, (2) energy consumption, and (3) message latency of a message-oriented system. Note that that design environment might not be the best fit for your project, and you will need to integrate FLAME into your design environment.

Deployment-wise, FLAME has three sides: (1) server-side, (2) detector-side, and (3) architect-side. In the following sections, this user guide, for each of those sides, will list the prerequisite software packages as well as the detailed steps you need to follow in order to install and launch FLAME.

The High-level architecture of FLAME

The rest of this guide is organized as following:

  1. Setting up FLAME Components
    1. Architect-Side Preparation
    2. Server-Side Preparation
    3. Detector-Side Preparation
    4. Slave Nodes Preparation
  2. Launching FLAME Components
    1. Launching FLAME Server
    2. Launching Detection Engines
    3. Launching FLAME Client
  3. Final Note

Setting up FLAME Components

Architect-Side Preparation

FLAME adds higher-order proactive conflict detection on top of a conventional copy-edit-merge collaborative software design environment. On the architect-side, FLAME attaches a modeling tool-specific adapter, FLAME Adapter, to the modeling tool to capture each modeling change as it is made via the modeling tool's APIs. A FLAME Client is installed at each architect's location to establish a channel between the architect-side and the server-side through which the captured modeling changes can be sent. For proactive conflict detection, each captured modeling change is immediately forwarded from the FLAME Adapter, through the FLAME Client, to the server-side.

Prerequisites

  • Microsoft Windows as the operating system
    • Windows 7 SP1, 8, and 8.1 have been tested
    • Full incremental updates recommended
    • Both 64-bit and 32-bit versions are compatible
    • This is because GME the modeling tool only runs on Windows
  • FLAME Client
    • Download FLAME Client [GitHub/Binary]
    • Download the Eclipse SWT library appropriate for your operating system [Eclipse]
  • Oracle Java
    • Java 7 or newer [Oracle]
    • Both x86 and x64 are compatible
  • Apache Ant
    • Newest version of Apache Ant [Apache]
    • Ant is necessary in order to build the FLAME source code
    • It is not required if you downloaded the binary distribution
    • Recent versions should work
  • Generic Modeling Environment (GME) 12.12.11 (32-bit) as the modeling tool

Steps to Follow

Configuring Java and Ant

  1. Add the path to the /bin directory of Java to the Path environment variable
  2. Set JAVA_HOME environment variable to the home directory of Java
  3. Add the path to the /bin directory of Ant to the Path environment variable
  4. Set ANT_HOME environment variable to the home directory of Ant

Registering the modeling paradigm (notation)

  1. Download the AssortedxADL paradigm for GME. [download]
  2. Open GME.
  3. Go to Tools → Register Paradigms.
  4. Click on Add from file.
  5. Browse to where you extracted the zip file and select AssortedxADL.xmp
  6. Click on Open and you will see that the paradigm has been successfully registered.

Registering the FLAME XTEAM-GME Adapter

  1. Get the FLAME Adapter. [GitHub/Binary]
  2. Open GME.
  3. Open a new project in the AssortedxADL paradigm.
  4. Go to Tools → Register Components.
  5. Click on Install New.
  6. Browse to and select CoDesign.dll
  7. Click Open.
  8. The FLAME XTEAM-GME Adapter component is now registered.

Getting the FLAME Client

  1. Get the FLAME Client. [GitHub]
  2. Unarchive the file if you downloaded the binary.

Getting the SWT library

  1. Get the SWT library that fits your operating system. [Eclipse]
  2. Unarchive the SWT.jar into the /lib directory of FLAME Client.
  3. Update the build.xml (line 17) in the FLAME Client directory to include the version of SWT you are using.

Updating the config.properties file

  • The config.properties file contains properties including the FLAME Server's hostname and port number, the model file that will be used during the design session, and the path to the GME executable.
  1. Go to the directory in which FLAME Client is located.
  2. Duplicate config.properties.template, and rename it to config.properties.
  3. Modify the configuration file using a text editor as you need.

Updating the XTEAM_Info.dat file

  • The XTEAM_Info.dat file contains the system requirements that FLAME will monitor. You should specify system requirement thresholds in this file so that FLAME can notify the users of newly arising design conflicts.
Line scheme of the XTEAM_Info.dat file

[Analysis type], [Column index in the .csv file], {[Target value] [operator] [threshold], ... }

Example XTEAM_Info.dat

Energy, 1, Total<7000000
Memory, 1, Maximum<30
Latency, 2, Average<7, Success>95

The interpretation of the above example XTEAM_Info.dat file is as following. FLAME will monitor three types of analysis: (1) energy consumption, (2) memory use, and (3) message latency. Each analysis type, in their corresponding .csv XTEAM simulation output, stores the data at the column number 1, 1, and 2 respectively. For energy consumption, FLAME will compute the overall summation of the values (Total) and validate if that is less than the threshold 7,000,000. For memory use, FLAME will find the maximum memory use of any component/connector at any point and validate if that is less than 30. Lastly, for message latency, FLAME will compute the average request-response time of all messages at every monitored interface and validate if that is less than 7. FLAME will also compute the success rate (number of responses / number of requests) and validate if that is greater than 95 percent.

Server-Side Preparation

The server-side Client Manager, which manages the connections between the server-side and FLAME Clients, receives the modeling change and forwards it to Detector Manager, which subsequently replicates and broadcasts the modeling change to all connected Detection Engines.

Prerequisites

  • FLAME Server
    • Download FLAME Server [GitHub]
    • Download the Eclipse SWT library appropriate for your operating system [Eclipse]
  • Oracle Java
    • Java 7 or newer [Oracle]
    • Both x86 and x64 are compatible
  • Apache Ant
    • Newest version of Apache Ant [Apache]
    • Ant is necessary in order to build the FLAME source code
    • It is not required if you downloaded the binary distribution
    • Recent versions should work

Steps to Follow

Configuring Java and Ant

  1. Add the path to the /bin directory of Java to the Path environment variable
  2. Set JAVA_HOME environment variable to the home directory of Java
  3. Add the path to the /bin directory of Ant to the Path environment variable
  4. Set ANT_HOME environment variable to the home directory of Ant

Updating the config.properties file

  • The config.properties file contains properties including the FLAME Server's hostname and port number, the model file that will be used during the design session, and the path to the GME executable.
  1. Go to the directory in which FLAME Client is located.
  2. Duplicate config.properties.template, and rename it to config.properties.
  3. Modify the configuration file using a text editor as you need.

Updating the XTEAM_Info.dat file

  • The XTEAM_Info.dat file contains the system requirements that FLAME will monitor. You should specify system requirement thresholds in this file so that FLAME can notify the users of newly arising design conflicts.
Line scheme of the XTEAM_Info.dat file

[Analysis type], [Column index in the .csv file], {[Target value] [operator] [threshold], ... }

Example XTEAM_Info.dat

Energy, 1, Total<7000000
Memory, 1, Maximum<30
Latency, 2, Average<7, Success>95

The interpretation of the above example XTEAM_Info.dat file is as following. FLAME will monitor three types of analysis: (1) energy consumption, (2) memory use, and (3) message latency. Each analysis type, in their corresponding .csv XTEAM simulation output, stores the data at the column number 1, 1, and 2 respectively. For energy consumption, FLAME will compute the overall summation of the values (Total) and validate if that is less than the threshold 7,000,000. For memory use, FLAME will find the maximum memory use of any component/connector at any point and validate if that is less than 30. Lastly, for message latency, FLAME will compute the average request-response time of all messages at every monitored interface and validate if that is less than 7. FLAME will also compute the success rate (number of responses / number of requests) and validate if that is greater than 95 percent.

Detector-Side Preparation

A Detection Engine is similar to a FLAME Client in the way that it is connected to an instance of the modeling tool with a local copy of the model internally, but a Detection Engine does not have an architect using the modeling tool initiating operations. Instead, it has an off-the-shelf conflict detection tool plugged into the modeling tool. An instantiation of FLAME may have multiple Detection Engines, each of which has a different conflict detection tool and may maintain a different version of the model. When a Detection Engine receives an operation that has been broadcast by the Detector Manager, the Detection Engine applies the operation to its local copy of the model, automatically invokes the conflict detection tool, and analyzes the outcome as an architect would do. The result of the analysis is then consolidated and delivered back to the architects via FLAME in the reverse order to that described above, i.e., from the Detection Engine, via the server-side components Detector Manager and Client Manager, and to the architect-side FLAME Clients.

Prerequisites

The prerequisites of the detector-side are identical to those of the architect-side.

Steps to Follow

The steps to follow for the detector-side are identical to those of the architect-side.

Slave Nodes Preparations

FLAME's detector-side has a component called Slave Manager, which manages a pool of slave nodes. Slave nodes may join the pool on-the-fly by initiating a connection to the Slave Manager, and the Slave Manager can asynchronously and simultaneously process several conflict detection instances by deploying the instances on the slave nodes.

A model of detector-side that uses slave nodes for conflict detection

This user guide will use Google Compute Engine as the cloud platform on which slave nodes are initiated and deployed.

Steps to Follow

Configuring to Google Compute Engine (GCE)

  1. Subscribe to GCE: https://cloud.google.com/compute/docs/
  2. Get the FLAME GCE scripts. [download]
  3. Update the variables.sh file in the FLAME GCE scripts.

Launching FLAME Components

Launching FLAME Server

  • > ant FLAMEServer

Launching Detection Engines

  • > ant DetectionEngine

Launching FLAME Client

  • > ant FLAMEClient

Final Note

Exploiting its architecture, FLAME can proactively inform an architect whether she has any outstanding higher-order conflict that she will find when she performs an update, even before she actually performs the update. In turn, the earlier finding of the conflicts may potentially lead to lowered cost and complexity in their resolution.

Should you have any questions, do not hesitate to contact me: Jae young Bang ()