Software Requirements Specification (SRS) Graphical Model ...This document provides a Software Requirements Specification (SRS) document for a Graphical Modeling Editing Framework

Template based on IEEE Std 830-1998 for SRS. Modifications (content and ordering of information) have been made by Betty H.C. Cheng, Michigan State University (chengb at chengb.cse.msu.edu)

Software Requirements Specification (SRS)

Graphical Model Editing Framework (GMEF)

Motorola 1 Final Draft Due December 7, 2006

Authors: Greg Heil, Andrew Holder, Karli Lopez, Josh Detwiler

Customer: Kabe Vanderbaan

Instructor: Dr. Betty H.C. Cheng

1 Introduction (Due Nov. 16)

This document provides a Software Requirements Specification (SRS) document for a Graphical Modeling Editing Framework (GMEF) that allows for the development of graphical model editors, which will then be used by programmers.

Section one of the Software Requirements Specification document details the purpose of the SRS document, and who the intended readers of this document shall be. Furthermore, we analyze the scope of the GMEF and provide an overview on the functionality in which it will provide to the users of the framework. Also, any definitions, acronyms, and abbreviations, which are used throughout this document, will be discussed within section one.

Section two describes the constraints and functionality that the software product itself will possess. Additionally, expectations of who will be using GMEF will be covered and how much experience is required in order to understand and manipulate the framework. Undocumented constraints, also known as assumptions, will also be covered in this section.

Section three highlights the main purpose for the GMEF and defines the hierarchy of specific system requirements in which the framework must adhere to. This section will specifically address, at a high level, the core functionality that is expected by the end user (a programmer).

Section four discusses the specifications of GMEF. It primarily describes multiple diagrams of the system including use cases, class diagrams, and state diagrams. Use cases of the system should reflect specific scenarios of the system, which are then depicted by sequence diagrams. Each goal within our goal diagram should relate to a specific use case. Our system’s state diagram should also capture each key class used within the system.

Section five introduces a prototype of GMEF and describes how the prototype functions, what is required to run the prototype, and sample scenarios that the prototype can represent.


Section six lists all of the documents, which are referenced throughout this SRS document.

Section seven informs whom to contact for any questions regarding the SRS document and the information contained within the SRS document.

1.1 Purpose The purpose of this document is to specify, in detail, the software requirements for

GMEF. This document describes the features of the framework, the constraints under which it will operate, and any external interfaces used by the framework. It also describes in detail specific requirements obtained from the customer specification and dialog between the requirements engineering team and Kabe Vanderbaan, our Motorola contact. The intended audience of this document are the stakeholders of GMEF. Current stakeholders include: the requirements engineering students, programmers creating editors with the GMEF framework, and users of these editors.

1.2 Scope The software described in this Software Requirements Specifications document is

referred to as Graphical Model Editing Framework (GMEF). The purpose of this software is to allow for the programmatic creation of multiple graphical editors, which modify an underlying model [2]. GMEF is a framework that relies heavily on abstraction, allowing for the manipulation of an underlying model designed using one of many available third-party modeling tools.

One problem that is apparent in some modeling languages is that they often try to encapsulate so much functionality that it often results in redundancy and infrequently used diagrams. Specifically, the Unified Modeling Language (UML) has been criticized for the complexity of its diagrams. However, GMEF enables a programmer to take an underlying model which may have been developed using, for example, Microsoft Visio and its UML templates, and create a unique tool set which incorporates the classes of the UML diagram as shapes, and offers its own set of connectors between the shapes to represent class relationships. Using a GMEF-powered programmatically created tool set and model editor, an end-user of the system may then graphically constrain the representation of an underlying model, something not generally allowed by UML.

An important goal of GMEF is that the framework must to be written as an Eclipse plug-in. Eclipse is an open, extensible framework for which software can be written for. In particular, Eclipse offers a Graphical Editing Framework (GEF) in which a programmer may develop a graphical modeling environment within Eclipse. One main advantage of designing an Eclipse plug-in is that these plug-ins are loosely coupled, and offer developers the freedom to choose exactly what they need for their specific applications. With such an open and customizable framework, it is quite clear that Eclipse offers the best features needed to realize the objectives of GMEF.

GMEF enables a programmer to create a graphical model editor along with a palette consisting of shapes and connections. An end-user of the system is presented with a workspace in which they are able to drag and drop shapes and connections from the


palette. GMEF will then interface between the underlying model and the current diagram that is being designed using the graphical model editor. Furthermore, any connections that are created or deleted within an active diagram will be reflected by its underlying model. Consequently, any changes that occur within our underlying model must then be reflected in any current opened diagrams. GMEF will also allow the user to save an open diagram in order that it may be reopened in future sessions and manipulated further. It is also required that GMEF may allow for the selection of elements. Once an element has been selected, it may be moved and / or deleted from the current diagram.

There are also several restrictions on the types of operations that GMEF may perform. GMEF will in no way be able to modify anything other than connections and relationships between shapes in the underlying model. All other model objects and properties must remain intact during the execution of a GMEF editor. Key requirements and constraints that GMEF should allow and forbid are discussed below.

1.3 Definitions, acronyms, and abbreviations

Following is a list of the terminology used throughout this SRS document as well as detailed tables of acronyms and definitions.

Acronyms

SRS Software Requirements Specifications GMEF Graphical Model Editing Framework GEF Graphical Editing Framework UML Unified Modeling Language API Application Programmer Interface GUI Graphical User Interface

Definitions Eclipse An open source development platform comprised of multiple

extendable framework. Programmer A programmer is a stakeholder who will be programmatically

creating the graphical editor along with the API framework [2]. End-user

An end-user of the system represents a stakeholder who will not deal with any programming but will solely use GMEF and a graphical editor to manipulate an underlying model [2].

Graphical Model Editor A graphical model editor is programmatically created and is considered a “workspace” in which a user may drag and drop shapes and connections to form a diagram of the underlying system model [2].

Framework A software structure in which another software project can be developed under. A framework may take multiple artifacts such as programs, dynamic libraries, and other content to link together multiple project components [1].

Plug-in Specific software which is developed and intended to function within an already exiting application [1].

GMEF Specific Definitions


Palette A container which will hold the shapes and connections programmatically defined within GMEF [2].

Shape A shape represents an abstraction of a core element of the underlying model [2].

Connector Represents a relationship between two elements within the diagram [2].

Diagram A diagram represents a current workspace within GMEF. A diagram can be thought of as a “view” into our underlying model. A diagram is an abstraction of our underlying model [2].

Underlying model The base model which was designed in a specific modeling language. This model will then provide GMEF with the specific shapes that will be contained in the palette [2].

1.4 Organization The rest of the Software Requirements Specifications document will discuss in detail

the product functions and constraints, assumptions of the system, the specific requirements that GMEF must adhere to, depict several models of the system in representative scenarios, a prototype of GMEF, and any references which were used throughout the SRS document.

The SRS document is organized in such a fashion where the actual software functionality is described first to aid in developing an idea of what GMEF should accomplish. Once the software is discussed thoroughly, the SRS document concentrates on specific requirements that the system must meet. These requirements are also reflected in various diagrams, including use case diagrams and state diagrams. The last section of this document presents a prototype for GMEF as well as sample scenarios depicting an end-user of the system would interact with GMEF.

2 Overall Description (Due Nov. 16) This section of the Software Requirements Specifications document discusses the

product, GMEF, and the core functionality, which is encapsulated by the system. Subsection one describes the context of GMEF and the type of system that GMEF

belongs to. Also, subsection one highlights several constraints of GMEF ranging from the system interface, user interfaces, and software interfaces.

Subsection two summarizes the specific functions that GMEF should perform which are then depicted as hierarchal goal diagram. The goal diagram of the system should include both high and low level goals.

Subsection three explains the specific expectations that an end-user of the system should possess. Specifically, this section will discuss what type of background a user of GMEF should have, what type of skill level is required to understand the system’s functionality, and what areas of expertise are required from the end user in order to operate GMEF.

Subsection four discusses specific constraints that the system must adhere to in order to properly function. This section also describes what types of conditions are encountered when these constraints are broken. Also, system critical properties are detailed and describe how they cause the system to fail.


Subsection five lists various assumptions, also known as undocumented constraints, which the system should abide by. The assumptions of GMEF should include software, environment, and user interactions.

Finally, subsection six discusses requirements of GMEF that are outside the scope of the product.

2.1 Product Perspective The GMEF toolset provides an Application Programmer’s Interface (API) that

enables a programmer to develop their own graphical model editor for a specific type of model. This API in turn, relies on extending the Eclipse Graphical Editing Framework (GEF) to provide an environment in which the editor functions, and the programmer can create a graphical editor and palette of shapes in order to modify an underlying model. GMEF provides an interface with which the programmer implements said editor for a given underlying model. Such instance of the GMEF editor allows a user to drag objects from a specified model into a working GMEF diagram. This diagram only shows the objects dragged by the user and any existing connections between these objects. The user can also add and remove connections between these objects as needed using the palette supplied, thus modifying the underlying model. However, GMEF cannot manipulate the actual objects in this model. GMEF also provides the capacity to save the visual state of an open diagram to a file.

The programmer must provide implementations of functions that draw objects and their connections, as well as functions that add and remove connections. The latter function will be handled by a specific event listener. Any changes made in real-time to the underlying model will also be updated in the diagram through a separate event listener.

The GMEF toolset primary interface is the Eclipse framework itself. This framework provides all necessary keyboard and mouse interfaces as well as the graphical interface. The only requirement made on the hardware platform is that it must be able to comfortably run an instance of the Eclipse software suite (i.e. CPU speed, memory, etc. must be sufficient). The event listeners in turn communicate only with third party modeling software already running in eclipse (see Figure 1, Data Flow Diagram) and do not need to communicate with any software outside of Eclipse. No further customizations other than those made by the programmer need to be done for instances of GMEF.

2.2 Product Functions The main functions of GMEF can be illustrated through two different use cases

that offer varied perspectives. The first use case scenario depicts the case in which a programmer uses the GMEF framework to create an editor for a specify type of model. The second use case depicts an editor user’s perspective. It is not necessary for this user to have any programming background or even know GMEF is the underlying framework in order to utilize the editor properly.

The way a framework provides functionality for a programming is by Application Programming Interfaces(API). GMEF will provide an API for a programmer build different types of editors. The programmer will specify properties the editor should have,


such the connectors available for use. The programmer will also specify the type model to be edited and how its objects will be drawn as well as implement the interface by which GMEF is notified of changes in the underlying model.

The second part of the GMEF framework is the user interface for editing the model. The framework allows the user to create and delete connections on a model. The model editor is to be built as an Eclipse plug-in, which provides a GUI environment for model editing and diagram creation, saving, and loading. An editor user will use GMEF to create, modify, and delete connections on an underlying model.

The editor itself is made up of a class selection box, a canvas, and a connections palette. The class selection box will display a shape with the details of the selected class onto the canvas. The user can add connections between the classes by selecting the type of connection from the palette and the classes involved. Connections between the classes will be handles by the framework, so repositioning of a class elsewhere on the canvas does not effect the connections.

Following is our goal model used to illustrate how each primary requirement is satisfied. Our primary Goal “Interface with GEF” depicts the need to provide a functional Eclipse plug-in using its plug-in framework.

• Interface within GEF – This is the top level goal. • Form Plug-In – Form plug-in is required using Eclipse. This plug-in displays an

editor, a palette, and navigates graphs. • Navigate Graph - The plug-in needs to be able to navigate a graph. • Create Connections – In order to navigate a graph, a graph has to exist. The

editor allows connection creation. • Create Palette – The plug-in needs to be able to create a palette of shapes and

connections. • Create Editor – The plug-in must create an editor for displaying classes as

shapes, creating connections, and moving them around via a GUI. • Save Description of Diagram – The plug-in must be able to save a description,

probably file, of a diagram created in the editor. • Allow Update Views - • Shape Compartments – The palette contains shapes and connections. The shapes

can contain zero or more compartments for types of data. • Manipulate Shapes – The palette allows different types of manipulations to

shapes, depending on selection. • Delete Element – An element may be deleted by selecting an item from the

palette. • Select Element – An element may be selected.


Figure 2. GMEF Goal Model

Create Editor Create Palette

Manipulate Shapes

Select ElementDelete Element

Allow Update ViewsSave Description of Diagram

Form Plug-In

Interface within GEF

Shape Compartments (0...n)

Create Connections

Navigate Graphs

2.3 User Characteristics The two types of users for this framework are: editor programmers and Eclipse editor

users. An editor programmer uses GMEF’s APIs to create a graphical editor for one of their models. An Eclipse editor user would use the GUI plug-in created by an editor programmer using GMEF. The programmer is expected to be proficient in Java to utilize the GMEF framework. The programmer must have the capacity to understand or learn the documentation and resources needed to utilize GMEF. The editor user is expected to be able to perform basic GUI operations, is familiar with the modeling language they are using and should understand that GMEF is editing a diagram of an underlying model.


2.4 Constraints General constraints within GMEF are of a limited scope. The GMEF toolset must

be able to work under the Eclipse GEF framework itself. GMEF must itself be written in Java. All programs that use this API must also be written in Java. The internal functionality of GMEF must also adhere to GEF’s own API requirements and style. Furthermore, event listeners must also conform to Eclipse’s own even handling scheme. GMEF runs as part of a single eclipse process and therefore has no need for advanced parallel operations or complex interfaces to external resources. The most important critical constraint within GMEF is that it must maintain the integrity of the underlying model. This means that underlying model objects cannot be created or destroyed by GMEF. Moreover, GMEF must allow the user to add and remove connections between objects as they please. It is also critical that GMEF editors run reliably and not cause any instability within eclipse or the system as a whole. Finally, concurrency constructs such as event handlers and listeners must be handled properly within GMEF. In addition to these critical constraints, diagrams must be properly notified when the underlying model changes. Should this not be the case, GMEF should handle such discrepancies between the diagram and the underlying model through an error message or by modifying the diagram as needed and logging the change. GMEF should also handle cases where a diagram retrieved from a file is corrupt and contains erroneous information. Two of these constraints can be demonstrated using SCR specifications. The first property (referred to as property 1) described is that which the GMEF editor allows users to add and remove connections between objects as they please.

Figure 3. Property 1 Mode Table Current Mode

ConnectEnd MarkDeletion VerifyDeletion CancelOperation New Mode

Idle @T - - - Connecting - @T - - Deleting Connecting @T - - - Idle - - - @T Idle Deleting - - @T - Idle - - - @T Idle The property’s Mode Table (Figure 3) shows us the basic behavior of this property. When connecting one end of a connector to an object, the system would send the ConnectEnd event. This event can be handled by both the Idle and Connecting states. The Idle state (being our initial state) will transition to Connecting when the user has initiated a connection. Once another ConnectEnd event has been received during the Connecting state (signaling that a second object has been selected,) the systems completes the connection and returns to the Idle state. However, if the user cancels the operation, no connection is made and the system returns to the Idle state. Upon receiving a MarkDeletion event (which signals that a connection has been marked for deletion) the system enters the Deleting state. The system may wish to receive confirmation from the user before deleting a connection, and so it waits for a VerifyDeletion event before


deleting the connection and returning to the Idle state. Alternatively, the system might not require verification, in which case the VerifyDeletion event automatically fires. The system may also interrupt the Deleting state via the CancelOperation event and thus keep the connection intact before returning to the Idle state. There are no relevant Event or Condition Tables for this property.

The second property (referred to as property 2) is that which handles discrepancies between the GMEF diagram and its underlying model. We assume that the diagram is modified in such a case and the change is logged.

Figure 4. Property 2 Mode Table Current Mode OpenDiagram ReadElement ElementRead InvalidID ResolvedError New Mode Idle @T - - - - LoadDiagram LoadDiagram - @T - - - LoadElement - - - @T - InvalidDiagram LoadElement - - @T - - LoadDiagram - - - @T - InvalidElement InvalidElement - - - - @T LoadDiagram InvalidDiagram - - - - @T Idle This property’s Mode Table (Figure 4) illustrates how GMEF can read a diagram from a file. The system initially responds to an OpenDiagram event while it is in its initial state Idle. The system then proceeds to load a diagram that corresponds to a known model. The system receives an InvalidID event if the model type is not found and will transition to the InvalidDiagram state. In this state, the system will alert the user of the error and after receiving the ResolvedError event, return to the Idle state. If the underlying model is found, the system will load the module (not depicted) and will wait for a ReadElement event, which indicates to the system that a new Diagram Element is being read. Upon receiving this event, the system will transition into the LoadElement state, where the system is concerned with loading a single element. The system receives an InvalidID event if the element’s ID is not found in the underlying model and will transition to InvalidElement. In this state, the system may alert the user of the change in the model, remove any connections associated with the defunct object, and after receiving the ResolvedError event, proceed to the LoadDiagram state in order to continue loading more diagram elements. (Alternatively, the system may stop loading the file and transition back to Idle after alerting the user of the error.) There are no relevant Event or Condition Tables for this property.

2.5 Assumptions and Dependencies An unavoidable problem during Software production is the presence of assumptions,

or undocumented requirements, during the design phase. GMEF is a Java-based platform-independent product capable of running on different types of systems. However, it is assumed that every GMEF client will be running the same version of Eclipse. Conflicts due to clients using an older version of Eclipse are beyond the scope


of this document, it is assumed that GMEF will be built using the latest version of Eclipse as of the time of writing.

GMEF, being Java-based, is designed to run across multiple platforms, ranging from Mac, Windows 9X/NET/XP, to Linux. We must assume that the client will have stable running versions of their operating systems and that all versions of GMEF will behave identically no matter what operating system they are running.

Furthermore, certain user interactions of GMEF are assumed to be known by the end-user. Specifically, the assumption is made that an end-user of GMEF should know whether or not it is logical to make a connection between certain shapes. That is, GMEF itself should not have to worry about erroneous connection, since the programmer and/or user will already know when these conditions may occur.

Due to the fact that GMEF is an Eclipse-based framework, the customer has specifically stated that hardware specifications are beyond the scope of this SRS document and have no need to be elaborated upon.

2.6 Approportioning of Requirements The customer does not have any requirements approportioned for future versions of GMEF.

3 Specific Requirements (Due Nov. 16) 1. Development of a Graphical Modeling Editing Framework (GMEF)

1.1. Framework should be created and deployed as an Eclipse plug-in [2]. 1.2. Framework should be build as an extension to the already existing Eclipse

Graphical Editing Framework (GEF) [2]. 1.3. Framework should save a description of a diagram into a separate file. This

allows for the diagram to be reloaded and later manipulated in its previous state [2].

1.4. Framework should allow for the creation of an Application Programming Interface (API) and a set of classes.

1.5 GMEF should be created as an Eclipse plug-in and should also conform to the best practices described in the book, Eclipse: Building Commercial Quality Plug-ins [2].

2. Programmatic creation of graphical model editors 2.1. A graphical model editor should be created via GMEF programmatically 2.2. Any modifications of a diagram within the editor should be reflected in the

underlying model. The same should hold true vice versa. 2.3. The graphical model editor shall consist of a palette. The palette should

contain various shapes, which represent the classes of our underlying model. 2.4. All shapes inside the graphical editor’s palette should conform to the

requirements of a given modeling language. 2.5. Shapes should be able to display “0…n” compartments. Compartments

resemble a class diagrams in which it holds three compartments: an


identification compartment, an attribute compartment, and an operations compartment [2].

2.6. Elements, or shapes, can be selected using the graphical model editor. 2.7. A selected shape may be moved and or deleted [2].

3. Connections 3.1. The framework of GMEF must ensure that all diagrams conform to the

properties of a graph. This includes that all shapes and their connections must be capable of being efficiently navigated assuming the graph is an undirected cyclic graph or a directed acyclic graph [2].

3.2. Connectors between shapes should be anchored to the center of these shapes. 3.3. A connector should allow for the creation of multiple vertices on the

connector. These vertices will provide the end-user a method for routing the connector within the diagram.

3.4. Connections made between two shapes should be done using an orthogonal procedure, otherwise known as “best guess”. This procedure will approximate an appropriate routing of a connector, which creates a visually organized diagram.

3.5. Connectors must have a distinct means to represent ends of a connection. An example would be using arrowheads to symbolize the end of a connection.

4 Modeling Requirements (1st draft: Nov. 28; Final draft: Dec. 7) Start of your text.

5 Prototype (Due Nov. 27, 5:00 p.m.)

5.1 How to Run Prototype

5.2 Sample Scenarios

6 References Start of your text. [1] D. Thakore and S. Biswas, “Routing with Persistent Link Modeling in Intermittently

Connected Wireless Networks,” Proceedings of IEEE Military Communication, Atlantic City, October 2005.

[2] K. Vanderbaan and D. Raymer “Graphical Model Editing Framework – MSU Requirements Engineering Proposal for Fall 2006” Networks and Infrastructure Research Lab, Motorola Labs, September 2006

7 Point of Contact For further information regarding this document and project, please contact Prof. Betty H.C. Cheng at Michigan State University (chengb at cse.msu.edu). All materials in this


document have been sanitized for proprietary data. The students and the instructor gratefully acknowledge the participation of our industrial collaborators.

Documents

Software Requirements Specification (SRS) Graphical Model ...This document provides a Software Requirements Specification (SRS) document for a Graphical Modeling Editing Framework