Vision Document - people.cis.ksu.edupeople.cis.ksu.edu/~sri/doc/phase_1/Vision Document 1.1… · Web viewSo BRUE adopts a scenario-based approach to understand an object-oriented

CIS 895 – BRUE Vision Document Version 1.1

Vision Document

For BRUEBehavioral Reverse Engineering using UML as

Eclipse plugin

Version 1.1

Submitted in partial fulfillment of the requirements of the degree of MSE

Sri RaguramanCIS 895 – MSE ProjectKansas State University

Page 1 of 20


Table of Contents

Table of Contents_________________________________________________________2

Introduction_____________________________________________________________4

Motivation____________________________________________________________4

BRUE________________________________________________________________4

Project Overview_________________________________________________________5

Overview_____________________________________________________________5

Themes_______________________________________________________________6

Functional Requirements Specification_______________________________________7

SR1 – Use case 1 – Launch BRUE_________________________________________8

SR2 – Use case 2 – Execute scenario______________________________________10

SR3 – Use case 3 – Visualize scenario_____________________________________12

Non-functional requirements____________________________________________15

Standards compliance_________________________________________________15

Usability___________________________________________________________15

Tools required__________________________________________________________20

Software___________________________________________________________20

Hardware___________________________________________________________20

Scope of the project_____________________________________________________20

Summary of Changes

Version # Date Changed By Summary Log

1.0 Sep 14, 2006 Sri Raguraman Initial draft of

document

1.1 Jan 28, 2007 Sri Raguraman Added non-

functional

Page 2 of 20


requirements.

Page 3 of 20


Introduction

Motivation

The motivation for this project comes from the lack of tools to help in understanding

object-oriented systems. To fully understand an object-oriented system, information

regarding its structure and behavior are required. There are a number of tools to visualize

static structure of object-oriented systems. They are usually based on analyzing source

code of a system. However, there are not many tools to visualize behavior of object-

oriented systems. Source code (or byte code) alone cannot be used to understand the

behavior of an object-oriented system due to the concepts of polymorphism, inheritance,

and dynamic binding inherent in every well-designed object-oriented system. The only

way to reverse engineer behavior is by executing the system and monitoring its

execution.

BRUE

The purpose of BRUE is to aid in understanding object-oriented systems. Eclipse is the

IDE of choice for most Java developers. C++ developers are starting to embrace Eclipse

as their preferred IDE. This tool will be implemented as an Eclipse plugin. By installing

the BRUE plugin, users will be able to run scenarios on any Java based system and view

both the static structure and dynamic behavior of the scenario. Package hierarchies

(including dependencies) and class diagrams will be used to show static structure of

classes involved in a scenario. Sequence diagrams will be used to show dynamic

behavior. All rendered diagrams will only show information that is relevant to that

scenario.

Page 4 of 20


Project Overview

od Overv iew

User

Run Scenario

Collect behav ioral data

Jav a/C++ Source/byte

code

UML2 Based model for scenario

View Scenario

Visualize model for scenarioPackage

relationships

Class Diagrams

Sequence diagrams

outcome

output

output

output

monitor

use

Figure 1: Project overview

Overview

Previous research in behavioral reverse engineering has concluded that at any point of

time, a user is usually interested in understanding just a part of a system, and not its

whole. So BRUE adopts a scenario-based approach to understand an object-oriented

system. The dynamic behavior of a scenario is visualized through sequence diagrams and

static structural aspects of the scenario visualized through class diagrams.

BRUE will provide the ability to launch an application from within Eclipse so that a

scenario can be executed. The scenario’s execution is monitored in order to collect

behavioral data. The behavioral data is stored as a UML model. The model is then

Page 5 of 20


rendered as a sequence diagrams. To visualize the static relationships of objects

interacting a in a scenario, class diagrams are generated that shows the relationships of

classes participating in the scenario.

BRUE will be built as a plugin for Eclipse. The plugin will leverage on a number of

Eclipse frameworks. The model that captures the behavioral and structural aspects of a

scenario will be stored in UML2 format by using the Eclipse UML2 framework.

Visualization of the model (rendering class and sequence diagrams) will be built over

Eclipse Graphical Modeling Framework (GMF). Eclipse Rich Client Platform (RCP) will

be used to design the user interface. Eclipse Java Development Tools (JDT) will be used

to analyze source code and generate static structural models.

Themes

1. Conform to industry standards

a. All rendered diagrams should conform to UML 2 standard.

b. The application should be seamlessly integrated into Eclipse, an industry-

adopted IDE.

2. Reusability: Leverage Eclipse frameworks wherever applicable. Parts of the

application that perform single core functionality should be built as a plugin of its

own.

3. Extensibility: Design the application such that the tool can be extended to create

other diagram types, such as, deployment diagrams, and state diagrams.

4. Usability: Smooth integration into the Eclipse platform and a user-friendly

interface should be a design theme for all user interface components. Every

interface to the user should strive for simplicity.

Page 6 of 20


Functional Requirements Specification

Figure 2: Use-Case model showing the core use-cases in the system

The following use-cases are critical and should be implemented in the system.

1. Set scope of types analyzed through BRUE

2. Run Scenario

3. Visualize scenario

a. Visualize Class diagram

b. Visualize package diagram

c. Visualize dynamic behavior

SR1 – Use case 1 – Launch BRUE

Tag: Critical

Page 7 of 20


This use-case describes the capability of launching BRUE and setting a scope for the

project intended to be analyzed through BRUE.

1.1 Actor

User is the primary actor of this use-case

1.2 Assumptions

A Java project is open in Eclipse. The project can be executed, i.e., it has a class

implementing the main() method.

1.3 Steps

1.3.1 User right clicks on a Java project

1.3.2 User selects “Run > BRUE” from the context menu.

1.3.3 The Eclipse “Run” wizard appears containing a launch configuration called

“BRUE”. The BRUE launch configuration contains fields for specifying,

Folder location to store scenario models.

Rules to specify which packages, classes, and methods need to be

included/excluded from BRUE.

By default all classes and all packages will be candidates for data collection.

However, user has the choice to exclude or include a specific set of packages,

classes, and methods. Wildcards should be supported in package names, class

names, and method names. Some examples are, “Include all methods within

package, org.myproject.*”, or “Exclude all methods that start with get

or set”.

An option to collect behavioral data during startup, (default – do not collect

data during startup).

1.3.4 System executes the selected project.

1.3.5 The project’s context will now have a new menu (invoked by right-clicking it)

called “BRUE > Start scenario” and “BRUE > Stop scenario”.

1.4 Variations (optional)

1.4.1 Eclipse cannot run the executable:

1.4.1.1 System will not perform step 1.3.5, instead user will be notified of the error.

1.5 Non-functional (optional)

Page 8 of 20


1.5.1 Most of the default parameters required to launch a Java application, such as,

class-path, the class containing the main method, etc., should be automatically

filled up by BRUE. Use the standard Eclipse Java launch configuration as a guide

– this will enable BRUE to be seamlessly integrated into Eclipse.

1.5.2 Any external JAR files and environment variables needed by BRUE to function

properly should be automatically set in its launch configuration.

1.5.3 Conform to Eclipse usability guidelines.

1.5.4 Launch shortcut and proper icons for the launch configuration should be used to

enhance user-friendliness.

1.6 Issues (optional)

1.6.1 If the application does not have a GUI, then the option to collect behavioral data

during startup should be checked. It would be preferable for BRUE to figure out if

it is a command-line application or a GUI based application.

Page 9 of 20

http://www.eclipse.org/articles/Article-UI-Guidelines/Contents.html


SR2 – Use case 2 – Execute scenario

Tag: Critical

This use-case describes the capability of instructing a launched application that the user is

about to execute a scenario. The launched application prepares itself to capture

behavioral data. Behavioral data includes details of all messages passed between objects.

For each message, its source, target, and parameter information is captured.

2 Actor


2.1 Assumptions

Use-case 1 has been completed.

2.2 Steps

2.2.1 User selects “BRUE > Start scenario” from the project’s context menu.

2.2.2 A wizard appears to guide the user in entering the following information

Name to identify the scenario.

2.2.3 System then instructs the launched application to start collecting behavioral data.

2.2.4 User executes a scenario in the launched application.

2.2.5 System captures behavioral data. The captured behavioral data conforms to

Eclipse UML2 standard.

2.2.6 User selects “BRUE > Stop scenario” from the project’s context menu.

2.2.7 System instructs the launched application to stop collecting behavioral

information.

2.2.8 System then generates two model files – structural model file, and behavioral

model file. A structural model file contains information regarding the packages,

classes, attributes and operations within classes. A behavioral model file contains

the interactions among objects relevant to the scenario.

2.3 Variations (optional)

2.3.1 The application is running without a GUI (headless)

2.3.1.1 Since there is no GUI, there is no user interaction. So the actor starts this use-case

at step 2.3.6.

Page 10 of 20


2.3.2 User had chosen to collect behavioral data during application startup in Use-case

1,

2.3.2.1 This use-case starts at step 2.2.6


2.4.1 The model file should be compliant to Eclipse UML2 standard. This will enable

other Eclipse plugins to re-use the UML2 model, if desired.


2.5.1 It is important that at least association relationships are identified between classes.

Refining association relationships to composition or aggregation is not a trivial

task and may be considered optional.

Page 11 of 20


SR3 – Use case 3 – Visualize scenario

Tag: Critical

This use-case describes the capability of visualizing the structural and behavioral aspects

of the scenario.

3 Actor


3.1 Assumptions

Use case 2 has been completed.

3.2 Steps

3.2.1 User navigates to the folder that contains the class diagram and sequence diagram

model files.

3.2.2 User right clicks on a model file and selects “View diagram”.

3.2.3 System renders the diagram appropriate for the model file.

3.3 Variations

3.3.1 Viewing Package relationships

The selected model file in step 3.2.2 is a model file regarding packages.

3.3.1.1 The following set of rules apply should be applied for any package relationship

diagram rendered by the system.

Figure

nameImage

Rule

Package

Applies to all packages

Dependency

Applies to all package relationships.

If a method in package A, calls a method in

package B, then add an arrow at B’s end. If both

packages are inter-dependant, then do not specify

an arrow.

Page 12 of 20


3.3.2 Viewing Class diagram

The selected model file in step 3.2.2 is a model file regarding classes involved in

the scenario.

3.3.2.1 The following set of rules apply should be applied for any package relationship

diagram rendered by the system.

Figure Name Image Rule

Class

Example Applies to all classes.

All rules that apply to presentation of classes, as

per UML 2.0 standard, should be followed.

Only show those methods and attributes that play

a role in the scenario.

Association

If class A contains one or more objects of class

B, then the two classes are related through

association. The notation may be decorated with

an arrow indicating the navigation direction.

Given the scope of the project, the decoration to

indicate direction is considered optional.

Refining the association relationship to

aggregation, or composition, may be considered

optional.

Generalization

If two classes that take part in a scenario are

related through generalization relationship, then

use this notation.

Page 13 of 20


3.3.3 Viewing Sequence diagram

The selected model file in step 3.2.2 is a model file regarding interaction between

objects involved in the scenario.

3.3.3.1 The following set of rules apply should be applied for any sequence diagram

rendered by the system.

Figure name Image Rule

Lifeline

Every class that

takes part in a

scenario interaction

should be rendered

using this notation.

Execution occurrence

An execution

occurrence is a

method execution

within the Lifeline.

Interaction Use

If a scenario calls

another scenario,

then a reference

interaction fragment

may represent the

second scenario.

Stop If a lifeline is

stopped

programmatically,

then this notation

should be displayed

at the end to denote

that the lifeline was

Page 14 of 20


terminated.

Message

A solid line directed

from the caller to

callee is the notation

for a method

invocation.


3.4.1 GMF already supports zoom in/out, and outline view. These should be used while

displaying any diagram.

3.4.2 Custom layouts should be used to display class diagrams. These custom layouts

should be used in such a way that the rendered diagram is aesthetically appealing.

3.4.3 GMF already supports automatic arrangement of the components within a

diagram. This feature should be invoked by default.


Non-functional requirements

Standards compliance

All rendered diagrams should conform to UML 2 standard

Model documents representing structural and behavioral information should be

stored in Eclipse UML2 standard.

Usability

While designing the user interface strive to adhere to the following user interface

guidelines. Refer to http://www.eclipse.org/articles/Article-UI-Guidelines/Index.html for

more details, if required.

Capitalization

Page 15 of 20

http://www.eclipse.org/articles/Article-UI-Guidelines/Index.html


o Use Headline style capitalization for menus, tooltip and all titles, including

those used for windows, dialogs, tabs, column headings and push buttons.

Capitalize the first and last words, and all nouns, pronouns, adjectives,

verbs and adverbs. Do not include ending punctuation.

o Use Sentence style capitalization for all control labels in a dialog or

window, including those for check boxes, radio buttons, group labels, and

simple text fields. Capitalize the first letter of the first word, and any

proper names such as the word Java.

Create localized version of the resources within the Eclipse plugin.

Error notification

o When an error occurs which requires either an explicit user input or

immediate attention from users, communicate the occurrence with a modal

dialog.

o If a programming error occurs in the product, communicate the occurrence

with a dialog, and log it.

Icons

o Use the Eclipse 256 color palette for creating the active or selected state of

all icon types.

o Use the Eclipse 8 color palette for creating the enabled state of

perspective, view, toolbar, toolbar wizard, and local toolbar icons. Use the

Eclipse 2 color palette for creating the disabled state of toolbar, toolbar

wizard, and local toolbar icons.

o Use the appropriate icon type in the location it is designed for within the

user interface.

o Follow the specific size specifications for each type of icon. Cut the icons

with the specific placement shown to ensure alignment in the user

interface. Follow the positioning guidelines for the different types of icons

for optimal alignment of these elements relative to one another.

o Abbreviate file name instead of using the full icon name, e.g. New

Interface becomes "newint".

Page 16 of 20


o Use transparent *.gif format for all user interface icons and wizard

graphics, unless the context requires a different file format.

Directory structure

o Follow the predefined directory structure and naming convention.

o Keep the original directory names provided.

o Minimize duplication of graphics within a plugin by keeping all graphics

in one, or few, first level user interface directories.

o Use lower case characters in your file names, e.g. DTD becomes "dtd".

o Use 10 characters or less in your file names if possible (underscores count

as a character).

o Use a file name suffix that describes its location or function in the tool,

e.g. newint_wiz.

Command

o Each command must have a label, tool tip, and full color image. The label

and tool tip must use Headline style capitalization.

o The command tooltip should describe the result of the command, not the

current state of the command. Use the text same as that for the command

label.

o A command should only be enabled if it can be completed successfully.

o Command enablement should be quick. If command enablement cannot

be quick, enable the command optimistically and display an appropriate

message if the command is invoked, but cannot be completed.

Dialogs

o When a dialog opens, set the initial focus to the first input control in the

container. If there are no input controls, the initial focus should be

assigned to the default button.

Perspective

o The size and position of each view in a perspective should be defined in a

reasonable manner, such that the user can resize or move a view if they

Page 17 of 20


desire it. When defining the initial layout, it is important to consider the

overall flow between the views (and editors) in the perspective.

The Navigator View

o Add actions to the Navigator View menu, toolbar, and context menu using

the plug-in registry.

o Use the attributes defined in IResourceActionFilter.java and

IProjectActionFilter.java to control the visibility of context

menu actions in the Navigator.

Windows

o Use an action set to share a set of actions, which are useful in two or more

views or editors.

o An action set should contain the smallest possible semantic chunking of

actions. Avoid the temptation to provide only one action set for an entire

plug-in. Define each action set with a specific task in mind. Use an Action

Set to contribute actions to the window menu bar and toolbar.

o Let the user control the visible action sets. Don't try to control it for them.

o Always use the global status bar to display status related messages.

Widgets

o For Tree and Table widgets that have a checkbox associated with a cell

item, changing the current selection should not automatically change the

check state of the selected item. However, the current selection should be

set to a given item when its check state is changed.

Standard Components

o If appropriate, add actions to standard components of Eclipse using the

plug-in registry.

o If you subclass or copy any of the standard components, always carry over

the standard components' characteristics.

Preferences

o Global options should be exposed within the Preferences Dialog. Expose

the preferences for a particular view, editor or window in the view itself,

via a menu or tool item.

Page 18 of 20


Accessibility

o All of the features provided by a tool should be accessible using a mouse

or the keyboard.

Page 19 of 20


Tools required

Software

1 JDK 1.4.1 or higher

2 Eclipse 3.2 with the following plugins

2.1 GMF 1.0

2.2 UML2 2.0

Hardware

The system will be built and tested on Windows XP.

Scope of the project

It is important to note that the scope of the project is primarily to build a tool that aids in

understanding an object-oriented system. Static structure is visualized through class

diagrams and package relationships. Behavior is visualized through sequence diagrams.

Page 20 of 20

Documents

Vision Document - people.cis.ksu.edupeople.cis.ksu.edu/~sri/doc/phase_1/Vision Document 1.1… · Web viewSo BRUE adopts a scenario-based approach to understand an object-oriented