requirements management tool for busy system analysts...

RambutanRequirements Management Tool for Busy System Analysts

Technical Report

Sasmito AdibowoFaculty of Computer Science

University of IndonesiaJuly 2003

Bibliographical Data Sheet

Report No. : UI-CS-2003-xxReport Date : July 2003Original Language : EnglishType of Paper : Technical Report

TitleRambutan – Requirements Management Tool for Busy System Analysts

Keywordsrequirements management, requirements engineering, extensible markup

language, requirements markup language, document object model, handheldapplication, personal digital assistant, design patterns, PalmOS, PocketPC,Windows CE, SuperWaba, Waba, Java, Swing, XML, RQML, DOM, Xerces.

Authors and Their Email AddressesSasmito Adibowo ([email protected])Eko K. Budiardjo ([email protected])

Performing Organization Name and AddressesFaculty of Computer ScienceUniversity of IndonesiaKampus UI, Depok 16424, IndonesiaPh. +6221 7863419 Fax +6221 7863415http://www.cs.ui.ac.id

Abstract

Rambutan is a Requirements Management Tool for Busy System Analysts. Theapplication consists of two programs, one for a desktop computer and the other for ahandheld computer. The desktop software is programmed as a Java Swing GUIapplication while its handheld counterpart is coded using SuperWaba and runnableon Palm OS, PocketPC, and Windows CE. Both applications are programmed with theJava programming language using established design patterns to support its evolution.

The conceptual foundations of Rambutan are based on Requirements MarkupLanguage (RQML), an XML dialect for storing natural-language requirementsdocument. In turn, RQML is based on a set of best practices in requirementsengineering. Therefore, Rambutan is independent of any particular requirementsengineering methodologies.

Supplementing Rambutan’s source code documentation, this report consists of ageneral description of the product, example screen shots of both applications,architecture overviews, and several pointers on evolving the system.

Total number of pages (including this page and cover page): 35

3

Table of Contents

General Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Product Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4User Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Product Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

User Interface Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Handheld Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Desktop Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Architecture Overviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24RQML Problem Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Evolution Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Evolving RQML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Adding missing features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Supporting multiple users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Upgrade issues to network-based user interface . . . . . . . . . . . . . . . . . . . . . 33Supporting other mobile device platforms . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4

1 General Description

1.1 Product FunctionsRambutan – Requirements Management Tool for Busy System Analysts is a set of end-user applications software that assists a system analyst in the gathering andcategorization of facts for a requirements specification document. In its current state,the product consists of two programs that perform similar functions. A handheldapplication is used to gather facts in the client's site while a desktop application is usedto edit and further refine the requirement statements in the analyst's office. Bothapplications allow the user to enter, modify, and display data that make up arequirements specification document.

The concepts behind Rambutan lies on RQML 0.9, an XML-based requirementsspecification document format [Gudg00]. In turn, Requirements Markup Language(RQML) is based on a set of best current practices in requirements engineering. Thisdesign decouples Rambutan from any specific methodology for requirementsengineering.

Both the desktop application and its handheld counterpart are implemented using theJava programming language, allowing them to share some common code. However,it is not possible to code both applications to the same API. The desktop applicationis programmed for the Java 2 Standard Edition platform, version 1.3. On the otherhand, the handheld application is programmed to run under the SuperWaba virtualmachine using its own API. Both applications are GUI-based single-user systems.

Compared to other requirements management tools, Rambutan offers these competitiveadvantages:

• Convenient client application for use in handheld (PDA-class) computers.• Portability between handheld platforms supported by SuperWaba: PalmOS,

Windows CE, and PocketPC. The handheld application may also be run on anyJava 1.1-compatible devices.

• Portability between desktop platforms supported by Java 2 Standard Edition:Windows, Macintosh, and Unix (including Solaris and Linux).

• Extensible pattern-based object-oriented design ([Gamm95]).• Open XML-based document format.• Independent from any specific requirements engineering methodology.• Non-restricting Apache-style open-source license.

1.2 User CharacteristicsRambutan is targeted toward mobile system analysts that performs extensive datagathering at the client's site during software development. These users typically usea handheld computer to assist their day-to-day tasks and also a desktop/notebookcomputer for heavier computing activities.

1.3 Product Path1.3.1 Handheld and desktop applications

Chapter 1 – General Description 5

Figure 1.1 Duet of Handheld andDesktop Applications

Figure 1.2 CollaborativeDocument Editing

This initial state of the product consists of a handheld and a desktop application foruse by a single user. The handheld application maintains data in its own proprietaryformat on the device. Its desktop counterpart is able to read, modify, and savedocuments in the handheld format. Natively, thedesktop application uses XML DOM to manipulatethe requirements document. The XML format usedis a subset of the proposed RQML 0.9 specification.

1.3.2 Desktop conduits

The next phase will be the development of conduitcomponents that allow the handheld application tocarry only a subset of the data available in thedesktop version of the requirements document. Thiswill allow the user to maintain large requirementdocuments yet still minimize memory requirementson the handheld.

These conduits should also provide synchronization facilities between the desktop andthe handheld. By synchronizing data, the user will be able to edit the same documentboth in the desktop and in the handheld computers. At synchronization time, data inboth of the modified documents will be merged in a record-by-record basis. Thissynchronization facility is similar to the one provided by PIM applications such as thePalm Desktop.

1.3.3 Collaborative document editing

Having attained a high usability for a single user requirement management tool, thenext step of the evolution should be in supporting team members involved inrequirements engineering. This support will be in the form of collaborative editing ofrequirements specification documents. Multiple users willbe able to concurrently modify the same document at theirown computers.

Multi-user functionality should be accomplished by usinga central repository that stores the requirements docu-ments. Users work on their desktop computers using datadownloaded from this central repository. Occasionally,applications on the desktop connect to the repository toreceive updates from other team members as well as tocommit its own updates to the repository. Handheldapplication still synchronizes with its desktop counterpart.Thus, the desktop application acts as a middle-tier be-tween the handheld and the repository.

Going multi-user also implies that there will be conflicts among the users of thesystem. These conflicts may range from simple concurrency problems to contradictingrequirements even to modifications made by one user that negates the work of anotheruser. Concurrency problems should be solvable by means common in the operatingsystem and database domains – using techniques such as locking, semaphores, andtransactions. While problems beyond concurrency are pertained to the problem domainwhich is requirements engineering.

Conflicts on a level higher than concurrency problems are solvable by providingrevision control and history functionalities. Each modification of a requirement


statement is recorded along with the user who performed the modification. Shouldconflicts arise, the system will be able to provide historical data that assists in conflictresolution. Furthermore, keeping a history of each requirement allows traceabilityinformation between requirements to extend into the dimension of time.

Additional "nice-to-have" features in this phase might include:

• Discussion/messaging facilities.• Group scheduling tools.• Group polling (decision-making) tools.• Shared contact list data (to keep in touch with stakeholders).1.3.4 On-line multi-faceted requirements management system

Requiring the use of desktop applications for collaborative requirement engineeringmay prove to be inflexible in the long run. Being a thick client, the application mustbe installed in the user's computer before use – making it more difficult to upgrade andteam members may be running different versions of the same application. Whenconnecting to the central repository, the desktop application may also require asignificant amount of network bandwidth – which may only be provided in a LAN-basedsetup. Finally, desktop GUI applications do not extend well to B2B informationsystems in which the back-ends of two companies communicate to each other directly.

These cases might not be optimally served using the configuration described in theprevious section:

• Team members working remotely. A reliable network connection might not be available when a user is working outof the office. He or she might be forced into using a dial-up network connectionor even mobile wireless data uplink (such as GPRS). Connection difficulties areespecially true when the user in question is working offshore – airtime connectionfare might be expensive and bandwidth will be low.

• Giving access to nontechnical stakeholders.One fine advice in management is to Put the Customer in Control [Kawa95].Therefore, it might be desirable to provide some access for stakeholder-customersto the requirements management system. Since these users are typically non-technical, they will require a different set of user interfaces and/or devices (forexample, they might not want to use a PDA).

• Subcontracting the development of subsystems.When developing large systems, it may be necessary to subcontract parts of thesystem's development to another company. This company may use different toolsin their requirements engineering process. Even if they use the same set of tools,it will be necessary (for business-politics reasons) to restrict their access to therepository.

Those aforementioned cases might be tackled by providing heterogeneous accessmethods to the requirements management system. Each of the access method shouldtarget a certain class of user and available connectivity option. The following tableoutlines some of the possible access methods available in present-day technologies.


Client Type Thick Client Thin Client

Enterprise Servers Enterprise JavaBeans Web Services

Desktop/NotebookComputers

Swing applicationHTML-based JSP application

Swing WebStart application

Handheld (PDA-class) Computers SuperWaba application

Small-screen optimized XHTML-based JSP application

WML-based JSP applicationMobile Telephones J2ME CLDC application

Furthermore, a prototype of HTML-based JSP application for requirements managementwas already developed by Dharmawan [Dhar02]. This prototype is also based onRQML.1.3.5 Software Development Information System

Requirements engineering in itself covers only a fraction in the broader context of theactivities involved in software development. Any non-trivial systems engineering effortwill gain advantage from an integrated set of tools that encompasses the requirementelicitation, analysis and design, construction, testing, deployment, and maintenanceactivities. This toolset should include the following:

• Requirements management tools.• Project management (including human resource management tools).• Analysis and design tools (including code generators).• Rapid application development tools (code templates and user-interface builders).• Source code revision control.• Testing framework (including automated unit and integration testing tools).• Deployment and upgrade tools (including Internet-based setup tools).• Maintenance tools (to handle field-discovered bugs and user feedback).Fortunately, software applications that cover various subsets of the aforementionedtoolset have been developed. Some of these applications may even be obtained at nocharge and some of which are open-source. On the down side, integration among theexisting tools provided by different vendors is minimal, or even nonexistent.

Although integrating the various tools in software development is a task not to be takenlightly, advantage gained by doing that is of great value to the industry. An integratedtoolset will be able not only to link a requirement to a feature – but further to designdecisions, on to software modules, lines of codes, and even to bug reports and thepeople in charge of fixing the bug. All of this will enable stakeholders to gain a real-time view of the development effort in progress. Furthermore, efforts to gather andanalyze productivity measurement statistics (lines of codes, function points, bug count,etc.) that were done manually may mostly be automated.


scop

e

usabilitymethodology

quality

Figure 1.3 The three aspects inRambutan's evolution

The following is a list of open-source tools that assists in the process of softwaredevelopment. These software tools are obtainable at no cost in terms of license fees.Note that this list is provided only for convenience – it is in no way complete.

• SourceForge (collaborative web-based software development) http://sourceforge.net/projects/alexandria-dev/

• hoot (Summary Process improvement for open software projects) http://hoot.tigris.org/

• Apache Maven (project management and comprehension tool) http://maven.apache.org/

• Tutos (web-based project management and groupware software) http://www.tutos.org/

• Progect (Palm-based project management software)• Concurrent Version System (source code version management)

http://www.cvshome.org• Subversion (source code version management) – http://subversion.tigris.org• JavaNCSS (source code metric analyzer) –

http://www.kclee.com/clemens/java/javancss/• Jakarta Cactus – Test framework for server-side Java code –

http://jakarta.apache.org/cactus/1.3.6 Horizontal Aspects

The preceding sections primarily focus on evolving the system vertically. Expansionpaths are outlined step-by-step in manners of increasing scope and features. Howeverthere are other horizontal aspects of the software that must not be left out. Theseaspects are:

• Supported requirements engineering methodologies.• Usability aspects – user friendliness, performance,

reliability, etc.The foundation of RQML is a set of best practices inrequirements engineering selected by Wiegers [Wieg99]. Itis still debatable whether this set is indeed "best" in thecurrent state of the industry. Also RQML is still far frombeing an accepted standard for requirements specificationdocument. One reason which hinders acceptance is thatthere are still inconsistencies present in [Gudg00]. Further refinements will need tobe done to iron out these wrinkles from the proposed RQML 0.9 specification.

Being fully-featured may not be best in all cases. Software packed with too muchfeatures will be large and difficult to use. This is especially true in handheldapplications, where the feature set must be carefully selected to achieve a delicatebalance in terms of features, ease-of-use, memory consumption, and speed [Palm].

Unfortunately, evolution of those horizontal aspects cannot be plotted as easily as thevertical aspects. Extensive research and trial-and-error attempts will be required inorder for the system to mature in these areas. Even so, quality of the system will beimproved gradually when the expansion of scope is made in-line with the improve-ments in usability and methodology.

9

Document List Element List

Element Edit

Figure 2.1 Handheld User Interface States

Figure 2.2 (A) The Document List screen. (B) Tapping on New to create anew document.

2 User Interface Design

2.1 Handheld Application

2.1.1 Flow Description

There are three primary screens in the handheld application. They are Document List,Element List, and Element Edit. Occu-pying all of the handheld display area,only one of these screens is shown at atime.

The handheld application starts at theDocument List screen showing the listof requirements documents availableon the handheld, if any. Tapping onthe name of a document will open thatdocument. There is also a New com-mand button at the bottom of the screen that is used to create a new document. Whenthe user taps on the New button, a dialog box will appear prompting for the name ofthe new document. After the user provides a name, the new document will be createdand then opened as if the document has already existed and he or she taps on itsname.

Opening a document will display the Element List screen, displaying the document'sname in the screen's title-area. This screen is actually a set of screens in which eachlists a certain type of RQML first-class elements, displaying its ID and Name attributes.

Chapter 2 – User Interface Design 10

Figure 2.3 An Element List screen. This one displays the available Use-case elements in the document.

Switching between the first-class element type displayed is done through a combo boxin the upper-right side of the display. Tapping on the title-area will display a pull-down menu where the user may create a new RQML first-class element of the desiredtype. While tapping on the name of a first-class element will edit that element.

Three command buttons are provided at the bottom of the Element List screen:

• New – to create a new first-class element of thetype currently displayed.

• Close – to close the currently displayed docu-ment and return to the Document List screen.

• Delete – to delete the currently displayed docu-ment and return to the Document List screen.

This user interface arrangement mimics the style ofsome of the PalmOS built-in applications. TheAddress Book, To Do List, Memo Pad, and Mailapplications all have a "category switch" combo boxin the upper right and a row of command buttons atthe bottom of the screen.

When the user creates a new element or opens anexisting one, an Element Edit screen is displayed.This screen is also a set of screens where each isused to modify a particular set an RQML first-classelement’s attributes. In these screens, the categoryswitch combo box is used to switch between views ofthe same first-class element being edited. The titlearea of these screens displays the type of the first-class element being edited.

Currently, the Element Edit screens do not provide any menu; commands are providedas a row of buttons at the bottom of the screen. All of these commands return to thepreviously active Element List screen:

• OK – Commits changes to the element.• Cancel – Abort any change to the element.• Delete – Deletes the currently displayed element.The Element Edit screens for the first-class elements Requirement, Stakeholder,Assumption, and Issue are identical as they do not add any information to RQMLFirst-Class. While the editors for other first-class element types add their own specificdisplays for their extra attributes.


1Source code documentation is provided in the accompanying CD-ROM.

Figure 2.4 Sample Element Edit screens displaying the common attributesfor all RQML first-class elements. The attributes are divided into two screens(A) and (B) to fit the display. Exactly the same set of view is used for theRequirement, Assumption, Stakeholder, and Issue first-class elements sincethey do not add any attribute beyond those common ones displayed in thisfigure.

The user interface of the handheld application is implemented in these packages:

• com.arcle.rmt.superwaba.ui – Generic user-interface classes.• com.arcle.rmt.superwaba.vc – User-interface classes.• com.arcle.rmt.superwaba.vc.rqml – RQML first-class element editors.More complete description the classes is available in the source code documentation1.

2.1.2 Additional First-Class Attributes

2.1.2.1 ProjectApart for standard attributes, the editor for the Project first-class element adds thefollowing sub-screens:

• Problem Statement• Product• Scope & Vision


Figure 2.5 Additional attributes for the Project first-class element type

2.1.2.2 Use-CaseApart for standard attributes, the editor for the Usecase first-class element adds thefollowing sub-screens:

• Actors• Conditions• Comments• Normal Course• Alternative Course• Exception


Figure 2.6 Additional attributes for the Use-case first-class element type

Figure 2.7 Additional attributes for the Use-case first-class element type


Figure 2.8 Additional attributes for the Context and Lexicon first-classelement types.

2.1.2.3 Context and LexiconApart for standard attributes, the editor for the Context first-class element adds aContext sub-screen. While the editor for Lexicon adds a Definition sub-screen.

2.2 Desktop Application

2.2.1 Overview

Layout of the desktop application’s user interface is mostly inspired from RationalRequisitePro. It is basically an MDI window with a tree view placed in the left. Thedesktop area is used to display first-class element editor windows.


Active documentfile name File modified flag

Docu

men

t Tre

e First-Class Element Type

Active Element

First-Class Element

Active ElementDescription

Desktop Area

Status BarFigure 2.9 Desktop User Interface Overview

The Document Tree at the left of the window displays the first-class element types asthe folders in the tree. Each first-class element type node in the tree contains theelements for that element type. Double-clicking an element type node creates a first-class element of that node's type. While double-clicking an element node will displayan editor window for that element. New elements may also be created through theRequirement pull-down menu.

The Active Element Description box just below the Document Tree displays thedescription attribute of the currently highlighted element in the tree. It is serves as aquick view when browsing first-class elements in the document – without the need ofediting the element.

The Desktop Area is used to contain first-class element editor windows. Takingadvantage of the richer user interface capabilities of the desktop, this area is capableof displaying multiple editor windows at once.

The Status Bar is an area at the bottom of the window to display status information.This area is reserved for further development; it currently has no function.

The user interface of the desktop application is implemented in these packages:

• com.arcle.rmt.j2se.swing

Main window and "about" dialog.


2 Source code documentation is provided in the accompanying CD-ROM.

Figure 2.10 First-class element editor window, displaying the Basic tab.

• com.arcle.rmt.j2se.swing.ui

Generic user interface classes.• com.arcle.rmt.j2se.swing.vc

User interface classes.• com.arcle.rmt.j2se.swing.vc.rqml

First-class element editors.More complete description the classes is available in the source code documentation2.

2.2.2 Element Editors

The first-class element editor windows are internal frames placed in the Desktop Area.Similar to the handheld application, each editor window contains several sub-viewsthat house their own set of controls for editing the first-class element. In the desktopapplication, the sub-views are placed in a tabbed pane within the editor frame. Thereare two command buttons placed at the bottom row of the windows:

• Close – closes the editor window and commits the changes done.• Delete – removes the corresponding element being edited from the document and

then closes the editor window.2.2.2.1 Common AttributesThe Basic and Extended common sub-views of the first class editors are similar to theones found in the handheld application. These sub-views exists for all first-classelement editors. Identical sub-views are used for the Requirement, Stakeholder,Assumption, and Issue first-class elements since they do not have any additionalattribute besides the common ones.


Figure 2.11 First-class element editor window, displaying the Extended tab.

Figure 2.12 The Project first-class element editor displaying the ProblemStatement tab

2.2.2.2 Project specific attributesThe editor for the Project first-class element type contains these additional sub-views:

• Problem Statement• Scope & Vision• Product


Figure 2.13 The Project first-class element editor displaying the Scope &Vision tab

Figure 2.14 The Project first-class element editor displaying the Product tab

2.2.2.3 Use-case specific attributesThe editor for the Usecase first-class element type contains these additional sub-views:

• Actors• Conditions• Courses• Comments


Figure 2.15 The Usecase first-class element editor displaying the Actors tab

Figure 2.16 The Usecase first-class element editor displaying the Conditionstab


Figure 2.17 The Usecase first-class element editor displaying the Commentstab

Figure 2.18 The Usecase first-class element editor displaying the Coursestab

The Courses tab is further divided into three identical sub-views:

• Normal Courses• Alternative Courses• Exceptions


Figure 2.19 The additional attribute of the Context first-class element editor

Figure 2.20 The additional attribute of the Lexicon first-class element editor

2.2.2.4 Context-specific attributesLike its handheld counterpart, the editor for the Context first-class element containsone additional sub-view.

2.2.2.5 Lexicon-specific attributesLike its handheld counterpart, the editor for the Lexicon first-class element containsone additional sub-view.


Figure 2.21 The default look-and-feel (Metal)

Figure 2.22 The Motif look-and-feel

2.2.3 Switchable Look-and-Feel

Swing supports the notion of pluggable look-and-feel in its components. Rendering ofeach Swing component is delegated to a separate Look-and-Feel Module. Therefore, acomponent may be rendered differently onscreen, depending on the active look-and-feelmodule. The active look-and-feel module may be changed at runtime, allowing a Swingapplication to "change its face" during execution.

Rambutan exposes this capability through the Tools menu. A command in this menuallows the user to switch between installed look and feel modules. The followingfigures shows samples of the application screens using the three look-and-feel modulesinstalled by default in JDK 1.3.


Figure 2.23 The Windows look-and-feel

It is visible that the pluggable look-and-feel is capable of emulating the user interfaceof the underlying operating system. On the other hand, it is also capable to mimic thedisplay of applications from another operating system.

24

Swing GUI SuperWaba GUI

J2SE API SuperWaba API

DesktopModel

HandheldModel

desktop application handheld application

RQML Abstraction

Figure 3.1 Architecture overview of thedesktop and handheld applications

SuperWaba GUI

SuperWaba API

Handheld Model RQML Abstraction

RQML Implementation

Figure 3.2 Handheld applicationarchitecture overview

3 System Components

3.1 Architecture Overviews

Rambutan consists of two application software: a desktop application and a handheldapplication. The desktop application is programmed to the Java 2 Standard EditionAPI (J2SE) while the handheld application is programmed to the SuperWaba API. Bothapplications are coded in the Java programming language. Using a commonimplementation language allows the two applications to share some common code –these cross-platform components contains simple algorithms and interface classes thatdo not rely on either API to function.

Both applications are roughly divided into twolayers: a user interface layer, and a data modellayer. Currently, the desktop application uses theSwing GUI library available with J2SE (note thatSwing is not the only user interface option availablein the platform). Since a handheld device is morelimited, the handheld application has little optionbesides using SuperWaba's GUI library.

The two applications share the RQML Abstractioncomponent. This component is a set of interfaceclasses that defines the RQML data model. In turn, these interfaces are implementedby both the Desktop Model and Handheld Model components. Access to the RQMLimplementations in both applications utilizes this abstraction as much as possible.Therefore consistency of the data models between the handheld and desktop isenforced – changes to these interfaces will ripple to both implementations in thehandheld and desktop. Likewise, a method signature change in the implementingmodel of one application will require the change to be mirrored in another application.

There are four top-level packages in Rambutan beneath the application's root packagecom.arcle.rmt:

• com.arcle.rmt.j2se

The desktop application.• com.arcle.rmt.superwaba

The handheld application.• com.arcle.rmt.rqml

RQML Abstraction interfaces.• com.arcle.rmt.xplat

Cross-platform utility classes.3.1.1 Handheld Application

The handheld application actually has three major layers:the user interface (GUI) layer, the data model layer, andthe RQML implementation layer. Being a shared compo-nent, classes in the RQML Abstraction layer is alsoincluded in the handheld application. All layers in thehandheld application rely on the SuperWaba API classes.

The GUI layer implements the user interface. Classes inthis layer mostly extend from SuperWaba's Window class.

Chapter 3 – System Components 25

Swing GUI

J2SE API

Desktop Model

DOM API

Xerces Implementation

RQML Abstraction

Element Adapters

Figure 3.3 Desktop applicationarchitecture overview

Access to the handheld's data by the GUI is done solely through the Handheld Modelor the RQML Abstraction layers.

Classes in the Handheld Model layer provide services to manage RQML elements to theGUI. Most operations done by the model rely only to the method signatures definedby the RQML Abstraction component to access the RQML elements. One majorexception to this includes object instantiations of the RQML elements (in which themodel acts as an abstract factory to its clients).

Since the classes in the RQML Abstraction are all abstract interfaces, they must beimplemented to be useful. Straightforwardly called the RQML Implementation layer,these classes implement those interfaces for use in the handheld application. Shieldedfrom the GUI by the Handheld Model and RQML Abstraction layers, internal implemen-tation changes to this layer will not affect the GUI.

Organized under the package com.arcle.rmt.superwaba, the handheld applicationconsists of these packages:

• com.arcle.rmt.superwaba.vc

User interface classes.• com.arcle.rmt.superwaba.model

Data model and RQML Implementation classes (located in a subpackage).• com.arcle.rmt.superwaba.ui

General-purpose user interface classes.• com.arcle.rmt.superwaba.util

General utility classes.• com.arcle.rmt.superwaba.framework

Interfaces for the MVC framework.3.1.2 Desktop Application

Similar to its handheld counterpart, the desktop application also consists of threemajor layers: the user interface, model, and RQML implementation. The RQMLAbstraction layer contains the same set of classes as in the handheld application. Alllayers in the desktop application rely on the J2SE API.

The user interface of the desktop application uses the Swing GUI library available inJ2SE. Although its functions are similar to the handheld, the desktop GUI takesadvantage of the larger screen and richer user interface capabilities typically availablein a desktop computer. Access to the data is also donesolely through the model and the RQML Abstractionclasses.

Since a desktop computer offers greater processing andricher user interface capabilities, the desktop model hasmore features to take advantage of this fact. Therefore,the desktop data model has different methods signaturesand implementations from the handheld’s model. Like thehandheld, it also relies on the RQML Abstraction inter-faces to manipulate the RQML elements in the model andacts as a factory class to instantiate their implementa-tions.

Implementation of the RQML Abstraction layer in the desktop application is differentfrom the handheld. Instead of storing RQML data itself, these classes rely on XML


3 Except for the <group> and <trace> first-class elements, which the elementsthemselves are not yet implemented.

SuperWaba to Java Bridge

Bridge FacadeImport Facade Export Facade

Copy FacadeFirst-ClassImporter

First-ClassExporterElement Copiers

J2SE APISuperWaba API

RQML Abstraction

Handheld & Desktop Models

Figure 3.4 Bridge architecture overview

DOM objects to represent the data in-memory. Therefore, classes in this layer arecollectively called Element Adapters. The DOM implementation library used is ApacheXerces, an open-source XML parser. Since these adapters communicate with theparser solely through the DOM interfaces provided, another DOM-compliant XMLparser besides Xerces may alternatively be used.

The desktop application is contained in these packages:

• com.arcle.rmt.j2se.swing.vc

User interface classes.• com.arcle.rmt.j2se.model

Data model and element adapter classes• com.arcle.rmt.j2se.swing.ui

Generic user interface classes.• com.arcle.rmt.j2se.util

Utility classes.• com.arcle.rmt.j2se.framework

Framework interfaces.3.1.3 Bridge Classes

The desktop application architecture shown in Figure 3.3 depicts only a part of thearchitecture. A Bridge component is purposely hidden from the picture to improve itslegibility. This component is used by the desktop application to access the handheld'sdata. It handles the conversion between the desktop and handheld models.

When the user opens a handheld document or savesa handheld document using the desktop application,its user interface calls the Bridge Facade to read thehandheld data and loads the data into the in-memorydesktop model and vice-versa. This facade in turndelegates the request to the appropriate ImportFacade or Export Facade components. The twofacades then handle the import or export, respec-tively.

The Import Facade uses a set of First-Class Importerclasses to load data from the handheld model into thedesktop. Each of these importer classes imports a certain type of first-class RQMLelement.

Analogically, the Export Facade uses a set of First-Class Exporter classes to save datafrom the desktop into the handheld model. Similar to the importers, there are one-to-one mappings between the element exporters and an RQML First-Class element type3.

Both of the import and export facades relies on a Copy Facade to transfer data betweenRQML elements. In turn, the facade uses a set of Element Copier classes to copy thedata. There are one-to-one mappings between a copier class and an RQML element(both first and second class elements). These copiers only depend on the RQMLAbstraction interfaces – they have no knowledge of the underlying implementations of


4 For example, platform differences would require a J2ME implementation ofRambutan to define yet another data model component.

RQMLSecondClass

External RQMLFirstClass Term

Taxonomy Requirement Stakeholder Usecase

Project Assumption Context Issue Lexicon Group

Trace

Figure 3.5 RQML data model hierarchy

these interfaces. Thus, the copiers may be used to implement RQML importers andexporters of other data models in the future4.

The import and export facades interact directly with the both handheld and desktopdata models. Acting as a client to both models, they fetch and store RQML databetween the two model instances.

Program code for the handheld model is run in the desktop so that the handheld-formatted data may be read and transferred into the desktop model. Although thehandheld model is programmed to the SuperWaba API, this is possible due to thesimulation layer (SuperWaba to Java bridge) provided by SuperWaba that allows itsprograms to run on Java 1.1. Thus, there is no need to duplicate code from thehandheld application to read the handheld-formatted data.

The bridge component is located in the package com.arcle.rmt.j2se.bridge and thefollowing sub-packages:

• com.arcle.rmt.j2se.bridge.copy

Copier classes and their facade.• com.arcle.rmt.j2se.bridge.swimport

Importer classes to load data from the handheld model.• com.arcle.rmt.j2se.bridge.swexport

Exporter classes to save data to the handheld model.

3.2 RQML Problem Domain

3.2.1 RQML Data Model

The RQML markup is constructed by the aid of an object-oriented data model. Thisdata model is a class hierarchy in which the classes define the kinds of data stored ina requirements document.

This object-oriented model is then mapped to an RQML DTD by flattening theinheritance tree and then defining XML tag types from the leaf nodes in the flattenedtrees. Simple data types (such as simple texts and enumerations) are mapped intoattributes of the element. While complex types are mapped into sub-elements. This


method of mapping is analogous to instantiating all of the classes and then creatingelement definitions derived from the objects that are instances of the leaf classes.

3.2.1.1 RQMLSecondClassThe RQMLSecondClass class defines attributes common for all RQML elements. Theseattributes are:

• ID – unique identifier for the element.• URI – reference to an external entity.3.2.1.2 TermThe term element is used in many other elements to make block in a natural languagetext targetable by a traceability link. This block then may be traced to lexicon entries,context entries, or for other traceability purposes. Currently, the term element is notyet supported by Rambutan.

3.2.1.3 ExternalThe external element is used in an RQML document to refer to entities outside thedocument. Since the referral method is through a URI, any entity that has one maybe linked from an RQML document. Currently, the external element is not yetsupported by Rambutan.

3.2.1.4 RQMLFirstClassThe RQMLFirstClass class defines common attributes for all entries in an RQMLdocument. Subclasses of this class are used to define markups for elements that areplaced immediately beneath the <rqml> root element. These elements are collectivelyreferred to as first-class elements. The common attributes across first-class elementsare:

• version – short textual version designator• status – enumerated value: proposed, approved, incorporated, validated.• stability – enumerated value: low, normal, high• difficulty – enumerated value: low, normal, high• priority – enumerated value: low, normal, high• name – short text• description – long text, may include terms.• rationale – long text, may include terms.3.2.1.5 Summary of first-class elementsThe following table provides an overview of the available first-class elements in RQML.These first-class elements are the XML-counterparts of the classes derived from theRQMLFirstClass class.

Each element is described in terms of:

• Additional Attributes – Attributes or sub-elements that are unique to thiselement apart from those defined by RQMLFirstClass.

• Description – The purpose of this first-class element.• Remarks – Further comments about the element.


First-classElement

Additional Attrib-utes

Description Remarks

<requirement> none Describes a naturallanguage requirement.

none

<stakeholder> none Describes a stake-holder.

none

<assumption> none Describes an assump-tion.

Minor inconsistencyfound in specifica-tion.

<issue> none Documents an unre-solved issue.

none

<use-case> - actor- precondition- postcondition- normal course- alternative course- exception

Describes a use-case. none

<project> - product- problem- scope- vision

Provides an overviewabout the project or itssubprojects.

Inconsistenciesfound in specifica-tion.

<taxonomy> - type element Classifies other first-class objects via a<trace> element.

none

<context> - origin- textual data

Provides context (e.g.problem domain infor-mation) that can berelated with other re-quirements.

none

<lexicon> - definition Stores a definitionabout a concept.

none

<group> - member Groups several first-class objects.

not implemented

<trace> - source- sink

Links two elements fortraceability informa-tion.

not implemented

3.2.2 Mapping RQML to classes

Object-oriented representations of RQML is put together by mapping the RQML datamodel into an interface hierarchy. Each RQML element is mapped into an interfacethat represents it. When common attributes or sub-elements definitions present, thecommonalities are re-factored into one or more super-interfaces. These interface

5 In fact, the only known “other RQML-based tool” is the one created byDharmawan [Dhar02]

classes are placed in the package com.arcle.rmt.rqml that are implemented by thedata model classes in the handheld and desktop applications.

A simplified approach was taken while mapping RQML DTD entries to Java interfaces.For every element that may have more than one sub-element of a particular type (thosechild element specifications that are suffixed with ‘*’ or ‘+’ in the RQML DTD [Marc99])is mapped to an interface which only allows one instance of the child element. Thereare three reasons that motivates this simplification:

• The discovery of several inconsistencies in the RQML specification in [Gudg00]signifies that the specification is not yet stable.

• RQML is yet to be a ratified standard by an international body (such as ISO,IETF, or W3C) so that this (short-duration) project need not be 100% compliantwith RQML to ensure interoperability with other RQML-based tools5.

• Technical difficulties in the implementation of an efficient user interface for thehandheld application to support such configuration of child elements.

Further developments of Rambutan should re-visit this design decision and perhapslift the limitations imposed by it.

The following is a fragment of the RQML DTD for the <requirement> first-class element:

<!ELEMENT requirement (name?, description*, rationale?)><!ATTLIST requirement

id ID #REQUIREDpriority (low | normal | high) "normal"difficulty (low | normal | high) "normal"status (proposed | approved | incorporated | validated) #IMPLIEDstability (low | normal | high) "normal"version CDATA #IMPLIED

><!ELEMENT name (#PCDATA)><!ELEMENT description (#PCDATA | term)*><!ATTLIST description

headline CDATA #IMPLIED><!ELEMENT rationale (#PCDATA | term)*>

This element is mapped into several interfaces, those are: RQMLSecondClass,RQMLFirstClass, and Requirement.

public interface RQMLSecondClass { public abstract java.lang.String getURI(); public abstract void setURI(java.lang.String URI); public abstract java.lang.String getID(); public abstract void setID(java.lang.String ID);}

Common to all first-class elements, the attributes priority, difficulty, status, andstability are enumerated types where a value may be chosen from a (very) limited setof values. These attributes are mapped to the int Java data type where the value ofthe enumerated types are specified through static constants. For example, to set thestatus attribute to the value approved the constant STATUS_APPROVED is used.


public interface RQMLFirstClass extends RQMLSecondClass { public static final int PRIORITY_LOW = -1; public static final int PRIORITY_NORMAL = 0; public static final int PRIORITY_HIGH = 1; public static final int DIFFICULTY_LOW = -1; public static final int DIFFICULTY_NORMAL = 0; public static final int DIFFICULTY_HIGH = 1; public static final int STATUS_PROPOSED = 0; public static final int STATUS_APPROVED = 1; public static final int STATUS_INCORPORATED = 2; public static final int STATUS_VALIDATED = 3; public static final int STABILITY_LOW = -1; public static final int STABILITY_NORMAL = 0; public static final int STABILITY_HIGH = 1;

public abstract Name getName(); public abstract int getPriority(); public abstract int getDifficulty(); public abstract int getStatus(); public abstract int getStability(); public abstract java.lang.String getVersion(); public abstract Description getDescription(); public abstract Rationale getRationale(); public abstract void setName(Name NAME); public abstract void setDescription(Description DESC); public abstract void setRationale(Rationale RATIONALE); public abstract void setPriority(int PRIORITY); public abstract void setDifficulty(int DIFFICULTY); public abstract void setStatus(int STATUS); public abstract void setVersion(java.lang.String VERSION); public abstract void setStability(int stability);}

The <requirement> first-class element does not define any unique attributes for itself.Therefore, the corresponding interface is empty – it does not declare any new methods.

public interface Requirement extends RQMLFirstClass {}

32

4 Evolution Management

4.1 Evolving RQML

Over time there will be a need to improve the current RQML support, or even to changethe RQML DTD itself. These changes will likely manifest in changes to the RQMLinterfaces in the package com.arcle.rmt.rqml. Modifications to these interfaces willripple mostly to the components described in this section.

4.1.1 Data Model Implementations

The implementation classes for the RQML interfaces will subject to a direct impactfrom RQML interface changes. These classes are located in the packages:

• com.arcle.rmt.superwaba.model.imp.rqml

• com.arcle.rmt.j2se.model.domimpl.rqml

4.1.2 RQML Copier classes

The classes that copies element instances through their RQML interface are the nextgroup of classes that will need to undergo modifications. Changing the RQML datarepresentations also mean changing the way to access these data – which includescopying the data. The RQML Copier classes that will require modifications are locatedin the package com.arcle.rmt.bridge.copy.rqml.

4.1.3 Import/Export classes

Changes to the RQML first-class elements will also impact the import and exportcomponents that transfer data between the desktop and handheld models. Theseclasses are located in the packages:

• com.arcle.rmt.j2se.bridge.swexport.rqml

• com.arcle.rmt.j2se.bridge.swimport.rqml

4.1.4 RQML First-class editors and their panels

Any change to an RQML element definition will affect their data-entry components.Changes to a first-class element will affect their corresponding editor components.Likewise, changes to a second-class element may affect one or more panels that areused by the first-class editors. These components are located in the packages:

• com.arcle.rmt.j2se.swing.vc.rqml

• com.arcle.rmt.superwaba.vc.rqml

4.2 Adding missing features

Incorporating effective support for the currently unimplemented RQML features –namely the <group>, <trace>, and <term> elements – will be a non-trivial task. Richeruser interface capabilities will be required to implement such features. Also, it isdoubtful whether the built-in components in the handheld environment are readilyavailable for the challenge – most likely custom user interface components will needto be programmed.

Support for the <group> element means adding a customizable view that displays acertain subset of first-class elements. The set of elements that are displayed in theview manifests itself to an RQML <group> element.

Chapter 4 – Evolution Management 33

Support for the <term> element means supporting wordprocessor-like capabilities tothe edit fields in the element editors. The edit fields should allow the user to mark oneor more groups of texts in the field and designate each group as a term. Then eachterm is linked to a lexicon entry for it. Accessing lexicon entries via the marked termsmay be done through a hypertext-like metaphor. The hypertext metaphor may also beused for see-also traces that links <term> elements.

Full support for the <trace> element may mean adding a hierarchical “outline” view offirst-class elements, to support the parent-type, parent, subproject, and refinementtrace types. A categorizing view may also be provided to support the instantiationtrace type.

4.3 Supporting multiple users

Collective experience shows that any non-trivial project will involve more than oneperson. Therefore, it makes perfect sense to evolve Rambutan to support multipleusers. As a requirements management tool, the primary targets for such evolution willlikely to support collaborative document editing and facilitating communicationsbetween the requirements engineers.

Adding support for concurrent users means moving the data storage from the user’smachines to a centralized system. A client/server setup will be necessary, althougha more limited thin-client environment may turn to be suitable for some uses. In anycase, a server will be needed to centralize handling of the requirement data and resolveconcurrency issues. The choice between setups may be weighted through severalfactors:

• Required user-interface capabilities – Normally a thick-client application is ableto provide faster interaction and thus better user experience while thin-clients arecharacterized by longer turnaround times between user inquiries.

• Maintenance of client applications – Obtaining upgrades for a thin-client(browser-based applications) are straightforward since the application is storedon the server – upgrading does not require user interaction. This is unlike thick-clients where upgrades are done by installing programs on the client’s machines.

• Network connectivity – A thin-client application is more dependent on thenetwork connection available while a thick-client may be able to operate while thenetwork is unavailable.

Before supporting more than one users, traceability support must already beincorporated. Most notably are the traces that handles versioning (revision control),conflicts, and replacement of one set of requirements over another.

4.4 Upgrade issues to network-based user interface

Supporting network-based user interface environments such as web or WAP willrequire another implementation of the user interface classes. However, the layersbeneath it – the data model and import/export classes – should not be affected by theexpansion. The bridge component may be useful to support handheld devices that areconnected to the server via a wireless network. Naturally, multi-user support is a pre-exquisite for the implementation of a network-based user interface.

The classes that will need to be re-implemented to support different user interfaceenvironments are located in the package com.arcle.rmt.j2se.swing and its sub-packages. Other user interface implementations should follow similar package naming

Chapter 4 – Evolution Management 34

6 news://news.falch.net/pilot.programmer.waba

convention. For example, a JSP/Servlet-based implementation preferably be placedin packages rooted from com.arcle.rmt.j2se.servlet.

4.5 Supporting other mobile device platforms

Should the need arise to expand support to handheld devices beyond those operatingon Palm OS and PocketPC, these options are available:

• Porting the handheld application – A thread in the SuperWaba newsgroup6

states that porting a J2ME application should to SuperWaba is not a difficult task– it can be done in two or three days. Porting to the other direction – SuperWabaapplication to J2ME – should not be too different, if the application does not useany of the advanced features of SuperWaba not supported by J2ME (for example,floating point or infrared communications).

• Porting SuperWaba – Albeit porting the SuperWaba virtual machine to othermobile operating systems (e.g. Symbian) will be more difficult than porting aparticular application, doing so may be more rewarding. Since SuperWabaalready supports two very different operating systems (Palm OS and PocketPC),adding support to another mobile operating system should not be impossible.

• Thin-client platforms – providing support to other mobile devices may also bedone by expansion to network-based user interface environments engineered forsmall devices, such as WAP. A JSP/Servlet version of Rambutan could beprogrammed that outputs WML pages instead of HTML.

35

Bibliography

[Dhar02] Dharmawan, Zulfikar S. Alat Bantu Requirements Management BerbasisWeb Dengan Memanfaatkan Dokumen Extensible Markup Language.University of Indonesia Research Paper. 2002.

[Gamm95] Gamma, Erich; Richard Helm, Ralph Johnson, and John Vlissides.Design Patterns: Elements of Reusable Object-Oriented Software.Addison-Wesley Publishing Company. 1995.

[Gudg00] Gudgeirsson, Gardar. Requirements Engineering and XML. University ofYork Research Paper. 2000.http://www.raqoon.is/rqml/rqml-resources.htm

[Kawa95] Kawasaki, Guy. How to Drive Your Competition Crazy. Hyperion, NewYork. 1995.

[Leff00] Leffingwell, Dean & Don Widrig. Managing Software Requirements: AUnified Approach. Addison-Wesley. 2000.

[Marc99] Marchal, Benoit. XML By Example. Que. 1999.

[Palm] et. al. Palm. Zen of Palm. Palm, Inc.

[Wieg99] Wiegers, Karl E. Software Requirements. Microsoft Press. 1999.