Requirements Analysis Document

STARS3 Project

15-413 Software Engineering

Fall 2000

Carnegie Mellon University

Pittsburgh, PA 15213






















Revision History:

Version R0.1 9/15/98 Robin Loh. Created

Version R0.2 9/14/98 Joyce Johnstone. revised template

Version R0.3 9/21/00 Joyce Johnstone. revised template

Preface:

This document addresses the requirements of the STARS3 system. The intended audience for this document are the designers and the clients of the project.
Target Audience:
Client, Developers
STARS3 Members:
(List STARS3 team members)
INSTRUCTIONS
We encourage you strongly to coordinate your section with other teams via Lotus Notes bboard, discussions in team meetings, architecture API meetings, documentation liaison and on the discuss bboard. Submission (must be a HTML document):
  1. Copy this document from the course homepage.
  2. The questions provided under each section are to help you brainstorm for ideas and offer suggestions. You must elaborate on them and produce coherent and descriptive paragraphs. Links to examples from the RAD of the JAMES project are also provided.
  3. Submit your RAD by posting them on the Review of Documents bboard.
MILESTONES

1.0 General Goals
The Interactive Electronic Technical Manual (IETM) database is designed to maintain detailed technical procedures and related information based on IETM guidelines.  The database will be accessible to the application server component via a well defined API and return relevant information in a timely manner.

2.0 Current System
The current system uses paper-based maintenance procedures manuals and technical information manuals which are aging, costly to maintain, and don't deliver information at the point of maintenance in an easy to use format.

3.0 Proposed System

3.1 Overview
The purpose of this project is to design a multi-modal IETM system compatible with level IV/V IETM requirements.  By multi-modal, we mean that users can interact with the system through speech or a web browser. Each command will link to pages or tasks within the database, containing graphics and text, to provide the mechanic with fast, updated, easy to access maintenance documents.

3.2 Functional Requirements
The functional requirement of the database component is to provide a well defined API which the Application Server subsystem uses to query the database.  Upon receiving a query and state information from the application server component, the database component will analyze the state and execute the query, returning the queried page in XML format.  The XML format will be defined by a DTD.  Example functions from our API include a search command which will allow searching for a particular string under a root node. Upon completion of the search, a list of links to the matching pages are returned.

3.3 Nonfunctional Requirements
The database must be well designed so that all queries can be returned in a reasonable amount of time.

3.3.1 User Interface and Human Factors
The database component only has the application server component as a user.  All "human" operations have to first go through the application server subsystem, which will interpret the users' action and send legal queries to the database component.

3.3.2 Documentation

The Database subsystem is not directly accessible to end users. Therefore, there will be no documentation addressed to end users. However, system administrator and managers will receive the XML DTD, the database schema, and documentation on the API to facilitate maintenance of the system.

3.3.3 Hardware Consideration

The database component will run on a server computer.  It is expected that a large enough server will be chosen so that response time of the database is not constrained by hardware issues such as I/O.

3.3.4 Performance Characteristics

The subsystem should process queries reasonably fast since there will be multiple queries and users.  The information that is received and transmitted should also be kept at a minimum to avoid delays and overloading the network.  However, the amount of data that needs to be returned from the Database subsystem may become a problem if the returned data included large amount of images. Therefore, due to the bandwidth needed for data, network speed should be at 10Mbps ethernet or higher. An alternate approach is to run the Database subsystem in the same computer as the Application Server subsystem. This will reduce the network bandwidth needed for communication between the Application Server and Database subsystem.

3.3.5 Error Handling and Extreme Conditions

The database (DB) component only "talks" to the application server (AS) component so the DB component only need handle erroneous input from the AS component.  Based on the current architecture, erroneous input would mean passing invalid Command objects to the DB component. For the Command object to be invalid, one of two conditions are met. The first condition is when the DB component does not know how to interpret the Command object, either because the command does not exist, invalid parameter values are used, or not all required parameters are included. The second condition is when the DB component is able to interpret the command, but is not able to execute this command in the current context. To pass the error to the AS component, an error object, defined in the XML DTD, will be returned. The error object should describe the error entirely, so that the AS component will be able to take the appropriate action.

Extreme conditions will be defined as database overload, i.e. too many connections.  When the database runs out of connections, it will spawn more to handle the extra request.  Spawning more connections decreases the performance of the database.  This will be a client decision whether or not to limit the number of connections for performance reasons.

3.3.6 System Interfacing

The database is expected to only interact with the application server on a frequent basis.  Since this interaction is within the overall system, the interactions are wholly self-defined.  For text input or modification, the database program should have an interface for authorized human modifications and is outside the scope of this project.

3.3.7 Quality Issues

The system should be reliable and accurate so that it returns the correct result in all circumstances unless an error is encountered.  If an error occurs, the system will trap the error in the input and notify the application server of the error.

The system should be portable to allow a switch of database programs without significant changes.

The system should be robust and have minimum downtime.  If downtime is required for updates or backups, then those should be handled at an hour that is convenient to technicians who are the primary human users.

3.3.8 System Modifications

The current database will be Microsoft Access.  Given MS Access' limitations however, it is expected that the database program will change in the future.  This should not be a problem since the database will be accessed using standard SQL and JDBC.  It is also likely that more functionality will be added as the system matures, to increase its flexibility.  If the database and current methods are carefully documented, then this should not be a problem either..

3.3.9 Physical Environment

We envision that the database server will run in a computer machine room or otherwise controlled and monitored environment.

3.3.10 Security Issues

The database should have sufficient protections to prevent users from making unauthorized changes to IETM data or having direct access to the database. The system should be resilient to network attacks and require strict logging of connections. As the machine is expected to be in a machine room, the room should have established physical access procedures to ensure only system administrators can obtain physical access.

3.3.11 Resource Issues

The system should be included in a nightly backup schedule. As the machine is envisioned to be stationed in a controlled machine room, procedures should already be in place for the backup of important data, and this machine should be included in such a program. Furthermore, a redundant server, constantly synchronized to the master, may be appropriate given the critical need for access to the data.  System installation and maintenance should be performed by trained computer technicians, which will probably be the client's internal IT division once they have been trained.

3.4 Constraints

The database component is primarily constrained by the chosen database program, SQL, and the Java language.

3.5 System Model

You will have to use the UML (Unified Modeling Language) to create the models. If the CASE tool is installed in the lab (Together-J), use it produce the models. To make your models more readable, you have to include some texts to guide the reader along the flow of your model. These text are called Navigational Text because they help to move the reader along the models.

3.5.1 Scenarios

The database interacts only with the application server component.  However, to determine various commands that it would use and how it would use them, a sample scenario is presented.

Homer comes in to work and checks in.  When Homer authenticates himself, somehow, the system knows that the bimonthly Helium Flushing System check needs to be done and instructs Homer to perform it.  To perform the check, Homer requires certain tools.  The database will either be queried again for the tools list or will have already returned it along with the task.  Homer then walks over to the system and starts the procedure.  At this point, the database is constantly involved, retrieving the "next" page and the next step that Homer will perform.  When Homer has a question, such as "Why do I have to wait?," then the database will now be queried about extraneous part information.  Homer also gives inputs to the system, such as the current pressure on the Helium valve.  These values will be returned to the database which will determine whether a new task or sub-routine will be needed.  Once the task is completed, Homer can take a break.

3.5.2 Use Case Models

3.5.2.1 Actors
The only actors are the application server subsystem and the database subsystem.

3.5.2.2 Use Cases
The only use case is where the application server queries us for information, which we then return.

3.5.3 Object Models

3.5.3.1 Data Dictionary
IETM:
The database will contain information on the physical plant and parts, along with various procedures and tasks.  The format of this data has yet to be decided in an XML DTD.

3.5.3.2 Class Diagrams
The only exposed method of the DB component is a runCommand method which takes the Command object and a state. DBMain will check for basic correctness of the Command object and return Output indication error if something is wrong, otherwise it will return whatever MapCommands of the DBLogic returns. DBLogic encapsulates all the logic of DB component, it will be responsible for mapping commands to SQL strings that will be run against database. It will also be responsible for changing the state. If Command can not be mapped to a valid SQL query, MapCommands returns Output object indication error. Otherwise, runSQL method of DBAccessor is run.


Figure 1. Database Class Diagram

3.5.4 Dynamic Models

The database currently offers four functions to the application server.  The first figure models the sequence for the NextPage() and GetPage() functions.  The second figure describes the SearchPage() and NextPages() functions.


Figure. 2 - NextPage()/GetPage()

Figure. 3 - SearchPage()/NextPages()

3.5.5 User Interface - Navigational Paths and Screen Mockups