Global 14
KWIC WRS v1.4
CS/SE 6362 Advanced Software Architectural Design (Spring 2011)
K.W.I.C.
(Key Words In Context)
WRS
Submitted to:
Dr. Lawrence Chung
Associate Professor,
Department of Computer Science,
The University of Texas at Dallas,
Richardson, TX -75080
Team Name: Global 14
Date
1/30/2011
2/8/2011
2/14/2011
2/20/2011
2/22/2011
Version
1.0
1.1
1.2
1.3
1.4
Description
Initial draft
Added Functional Requirements
Added NFRS
Systematic Decision Making
Added requirements Traceability Matrix to
Implementation
Author
Global 14
Global 14
Global 14
Global 14
Global 14
Developer’s Website: http://utdallas.edu/~sas071100/SAD/
1
Global 14
KWIC WRS v1.4
Table of Contents
Introduction ................................................................................................................................ 3
Project Overview .................................................................................................................... 3
Purpose .................................................................................................................................. 3
Version Changes .................................................................................................................... 3
Issues ........................................................................................................................................ 3
Functional Issues ................................................................................................................... 3
F1: ...................................................................................................................................... 3
F2: ...................................................................................................................................... 4
F3: ...................................................................................................................................... 4
F4: ...................................................................................................................................... 4
F5: ...................................................................................................................................... 5
F6: ...................................................................................................................................... 5
F7: ...................................................................................................................................... 5
Non-functional Issues ............................................................................................................. 5
NF1: .................................................................................................................................... 6
NF2: .................................................................................................................................... 6
NF3: .................................................................................................................................... 6
NF4: .................................................................................................................................... 7
NF5: .................................................................................................................................... 7
NF6: .................................................................................................................................... 7
NF7: .................................................................................................................................... 8
WRS Improved Understanding ................................................................................................... 9
Summary ................................................................................................................................ 9
The KWIC System .................................................................................................................. 9
Functional Requirements .................................................................................................... 9
Non-functional Requirements .............................................................................................. 9
The Deliverable .....................................................................................................................10
Requirements Specification ...................................................................................................10
Architectural Specification .....................................................................................................10
Prototype Implementation ......................................................................................................10
User Manual ..........................................................................................................................10
Requirements Traceability Matrix to Implementation .................................................................11
2
Global 14
KWIC WRS v1.4
Introduction
Project Overview
“Your team is to architect a simple KWIC software system and implement it, which later
will be used for a web search engine. For this project, you will use an Object-Oriented
architectural style, and build a Java applet (or an equivalent), which should be
accessible through your team’s web page.” – Project Summary Document.
Purpose
The product described within this document is Version 1.0 of the Key Word in Context
(KWIC) system. This system is used primarily as a backend tool for search engines, and
will be used as such in phase two of this project.
Version Changes
This will detail changes from the first to second phases.
Issues
“The KWIC (Key Word in Context) index system shall accept an ordered set of lines,
where each line is an ordered set of words, and each word is an ordered set of
characters”
Functional Issues
F1: The word accept implies verification; what type of error checking or input validation will be
required prior to running the circular shift?
O1: No error checking, leave the responsibility to the user and the user guide.
O2: Run spell checking to find minor typing errors.
O3: Filter noise words. (A, an, the, of, for, and, etc…)
O4: Check for any invalid characters as the implementation team defines.
Solution: O3 & O4
Rationale: Filtering noise words reduces the number of circularly shifted lines, which reduces
memory consumption and improves performance. In conjunction checking and removing invalid
characters simplifies searching for specific line(s) improving usability. These two options
3
Global 14
KWIC WRS v1.4
increase the performance of the system with minimum cost. Running spell check is beyond the
scope of the system.
F2: What set of characters are we expected to be able to input into the system, (i.e. %, $, &) ?
O1: All valid ASCII characters.
O2: All valid Unicode characters.
O3: Various other language characters.
Solution: O1
Rationale: Only allowing ASCII characters narrows the scope of both the
implementation and the user demographic of the system. Expanding the input to
include Unicode and other language characters would only expand the scope, resulting
in complications that are detrimental to the performance and reusability of the system.
“Any line shall be ``circularly shifted" by repeatedly removing the first word and
appending it at the end of the line.”
F3: “Any line” implies not all lines; should this be changed to say each line?
O1: This should be changed to reflect each line.
O2: Leave the requirement originally stated.
Solution: O1
Rationale: Each line needs to be circularly shifted. Otherwise the system will output an
incomplete set of shifted lines, which would hinder the available search results and
decrease performance.
F4: Appending at the end of the line could cut off punctuation; are we to even consider
punctuation in the circular shift?
O1: Associate punctuation with prior word.
O2: Ignore punctuation.
O3: Separate words on space.
O4: Remove punctuation for output except for compound words (as in the case
of hyphenated words).
Solution: O4
Rationale: Including punctuation in the circular shifts is unnecessary because the
search query would be void of punctuations due to filtering. Also comparing the query
with the shifted lines that contains punctuations would complicate implementation
(hindering reusability) and increase computation (decrease performance).
4
Global 14
KWIC WRS v1.4
“The KWIC index system shall output a listing of all circular shifts of all lines in
ascending alphabetical order.”
F5: This says we are to output just the output of circular shift; are we to include the
original statement or is that part of the output for circular shift?
O1: Include original statement in the output.
O2: Do not include original statement in the output.
Solution: O2
Rationale: The original statement may begin with a noise word and since the output
consists of circularly shifted lines that do not start with noise words, the original
statement should not be included.
F6: What types of input method shall we be expected to accept.
O1: Only be keyboard entry into the applet/program.
O2: Accept file reading.
O3: Input that is copy/pasted
Solution: O1, O3
Rationale: While reading an ordered set of lines from a text file is viable. In order to limit
the scope and maintain ease of use for the user, input is limited to only through
keyboard entry or copy/pasting from another source.
F7: Does the interim circular shifts need to be output or does only the alphabetized form
need to be printed.
O1: Both.
O2: Only the alphabetized circular shifts.
Solution: O2
Rationale: Outputting the interim circular shifts would result in redundant data, since the
alphabetized form already exists. In addition, including the interim shifts would hinder
performance when searching through the shifted lines.
Non-functional Issues
“The KWIC system shall be easily understandable, portable, enhanceable and reusable
with good performance.”
5
Global 14
KWIC WRS v1.4
NF1: What is “understandable”? Is this in relation to the GUI output or the code
implementation (for reusability in the second phase).
O1: Each GUI element will be clearly labeled with its intended functionality. e.g.
“Output”, “Input”.
O2: Comments and design practices of the code implementation will be able to
be extended in future development.
O3: A new user to the system should be able to enter lines and get them
alphabetized within 2 minutes of their first use of the system
O4: The user manual shall state clearly what each element on the screen does.
This shall be implemented using tooltips that are shown when the mouse pointer hovers
on objects.
O5: A help button shall be available at the top of the screen to provide directions
to users if they are confused about anything while using the system.
Solution: O1, O2
Rationale: The program should need no training. This means if someone sits down in
front of the computer they should be able to understand. The program also needs to be
easy for programmers to understand. This is so future programmers should not have to
spend a long time looking at the code before being able to adjust or tweak aspects.
NF2: What is “portable”? If it is an applet or equivalent hosted on a webpage would it be
considered portable?
O1: Accessible via internet.
O2: Accessible via Mac systems, Linux systems, and Windows systems.
Solution: O1, O2
Rationale: Anybody should be able to use the program with an internet connection. This
expands the user base. The program being non-platform specific also increases the
user base and allows for a wider of variety of users.
NF3: What is “enhanceable”? Does this refer to the ability of the overall KWIC system
to be enhanced into a search engine?
O1: The program needs to be able to accept updates according to a schedule
defined by the user; limited by the availability of updates.
O2: The program has plug-in support. (i.e., separate language plug-ins).
Solution: O1
Rationale: The program should be able to accept updates without problem. This
increases the lifespan of the project because you are able to add new things on. Plug in
6
Global 14
KWIC WRS v1.4
support is beyond the scope of this project, and there is too large of a time cost
associated.
NF4: What is “reusable”? Should the output be formatted in ways that phase 2 can
more easily use it or should the code implementation be documented enough so that it
can be easily extended?
O1: The implementation shall be conducted in a way that is adherent to the
design so that future implementation can easily use our work.
O2: Parts of the system should be used in the same style the system was
developed.
O3: The whole system should be used in various styles.
Solution: O1, O2
Rationale: Parts of the system should be able to be used in different contexts with the
same architecture style. This allows future development teams to adjust certain parts of
the code and would benefit future developers. The whole system should not be used in
different contexts because this would duplicate the whole system and is not feasible.
The cost of developing systems for different styles would hurt the design.
NF5: What is “good performance”? Does this mean that the program has few to no
errors when circular shifting? Or does it refer to the time that the KWIC system should
take to perform the task?
O1: The response of the system in terms of GUI should be quick and immediate.
(no longer than a two second response time for input consisting of less than 10 lines on
a system with, at least 1GB of RAM).
O2: Every circular shift should be sorted correctly, with none left out of the list.
Solution: O1 & O2
Rationale: Good performance encompasses both the speed and correctness of the
program. Having the user wait an excessive amount of time and providing incorrect
output constitutes as poor performance.
“The KWIC system shall also be user-friendly, responsive, and adaptable.”
NF6: What is “user-friendly”? Does this only refer to GUI?
7
Global 14
KWIC WRS v1.4
O1: Progress bar or timer: For large inputs the system can be expected to take
longer, however indications to the user like a timer or progress bar should be made to
assist the user.
O2: The GUI elements shall have labels and tooltips which say what they do.
O3: Provide a help function to assist users
O4: Provide a pop-up menu to assist users
Solution: O1, O2, O3
Rationale: The progress bar allows the user to realize that the program is no frozen and
because of this decreases user frustration. The GUI should be simple because an
average user should be able to immediately use the program. This allows users to be
more satisfied. There should be a help function if the user does not know what they are
doing. This is because there will be no hands on training with the program, so if users
have questions they should be able to get help. A pop-up menu may confuse the user
and because of this would decrease how user friendly the program is.
NF7: What is “responsive”? Does this refer to the KWIC system’s performance time?
And if so, then does “good performance” refer to something else?
O1: Two second wait time maximum as per “good performance.”
O2: The system will provide feedback, depending on what button is pushed. It
will “respond” to the user through a pop up dialog box.
Solution: O1
Rationale: The terms responsive and good performance refer to the same aspect of the
system and both are covered by the idea of a two second maximum wait time. A dialog
box to the user would impact how many clicks the user needs, so this is actually hurting
the
system.
NF8: What is “adaptable”? Is this covered by enhanceable and reusable or is there
more that this implies/entails?
O1: Multiple input formats as per Functional requirement 6.
O2: This is a reference to the enhanceability of the system is as defined in NonFunctional requirement 3.
Solution: O2
Rationale: The system should be modular, so that if one module is changed other
modules will work as intended. This would lead to a better design and decrease the cost
8
Global 14
KWIC WRS v1.4
of maintenance in the long run. Multiple input formats do not have to do with how
adaptable a product is, so this will not be included in this requirement.
WRS Improved Understanding
Summary
As system/software architects of a renowned company, your team is to architect a
simple KWIC software system and implement it, which later will be used for a web
search engine. For this project, you will use an Object-Oriented architectural style, and
build a Java applet (or an equivalent), which should be accessible through your team’s
web page.
The KWIC System
Functional Requirements
The KWIC (Key Word in Context) index system shall accept an ordered set of lines,
filtering out noise words and invalid characters, where each line is an ordered set of
words, and each word is an ordered set of ASCII (American Standard Code for
Information Interchange) characters. Input will be allowed via the keyboard and
operating system clipboard (copy and paste). Each line shall be ``circularly shifted" by
repeatedly removing the first word and appending it at the end of the line. The
punctuation will be removed for the purposes of output except in the case of in-word
punctuation (compound words, apostrophes). The KWIC index system shall output a
final listing of all circular shifts, excluding the original input, of all lines in ascending
alphabetical order.
Non-functional Requirements
The KWIC system shall be easily understandable in that both the average internet user
should be able to understand and use the final system and the comments and design
practices of the source code implementation will be able to be easily extended in future
development. The system shall be portable by enabling access via the internet and
allowing for cross-platform users. The system shall be enhanceable by allowing for
seamless and easy updates. The system shall exhibit reusability by conducting our
implementation in a way that is strictly adherent to the design so that future
implementers can easily reuse our work. The performance of the system will be
responsive (no longer than a two second wait time) and accurate in that every circular
shift shall be sorted correctly, with none exempted from the list.
The KWIC system shall also be user-friendly by offering user feedback in the form of a
progress bar and/or timer and help functions. The GUI design shall also consider userfriendliness by providing a simple enough design to allow a user to immediately know
the function of each element, such as providing them with tooltips. Responsiveness is
an aspect of performance in that the system shall provide user feedback within two
seconds. The system shall also be adaptable in that the implementation will be modular
enough to increase enhanceability and decrease maintenance.
9
Global 14
KWIC WRS v1.4
The Deliverable
Your description should be elegant and comprehensible. Your deliverable should be
available as both online (one URL per team member) and offline specifications
(submission of one copy per team). You can choose to use an (extended) IEEE-style
format for the deliverable, in which the major sections typically include: Introduction,
Main Body (items below, for this project), Glossary (Definitions and Acronyms) and
References (See, for example, "Document Templates - general IEEE" on the Internet or
course web site).
Requirements Specification
The functional requirements specification is incomplete (e.g., where should the input
come from, and the output go?). Describe any extensions, or clarifications, to the
requirements specification. The non functional requirements specification is also
ambiguous. Clarify each non-functional term repeatedly as many times as you'd see
necessary.
Architectural Specification
Describe both pictorially and textually, the architectural style, components and your
deliverable should also discuss the rationale in terms of the advantages and
disadvantages of your architecture, in consideration of several scenarios whenever
appropriate. Also describe all the constraints and patterns, if any. You should establish
traceability between the requirements specification and the architectural design
specification.
Prototype Implementation
Your program specification - well documented and tested, and an implementation of a
prototype system.
User Manual
A (preliminary) user manual should be developed, which should become more complete
and consistent at the end of the 2nd phase of the project. Describe how the user can
access and use the system, including the URL of each team's web site where your
applet, or its equivalent (and all other deliverables), can be accessed. Also briefly
describe essential scenarios --- the typical interactions between the user and the
system, e.g., what are the steps the user has to follow in using the system. Use
screenshots to show how the system looks like initially as well as to show subsequent
steps that the user might take.
10
Global 14
KWIC WRS v1.4
Requirements Traceability Matrix to Implementation
The following table shows the requirements traceability to the implementation of the KWIC
system.
FR1
Issues Functional
Component
Requirements
Input verification
Module input verifies all the inputs
System Feature [Screen Shot #]
(please refer to the figure below)
Input [5]
FR2
Sets of characters
Input [5]
FR3
Shifting each line
FR4
Punctuation
Module Circular Shift excludes circular Ouput [3, 6]
shift of punctuation
FR5
Exclude original
statement in the
output
Module Output doesn't output original
statement
Ouput [3, 6]
FR6
Input methods
Input medium accepts keyboard entry
and copy/pasted inputs
Input [5]
FR7
Only print the
alphabetized form
Module Output only outputs the
alphabetized form
Ouput [3, 6]
I-FR
NFR1
Issues NonFunctional
Requirements
Understandability
NFR2
I-NFR
Module input accepts all valid ASCII
characters
Module Circular Shift constructs
circular shift of each line
Component
Ouput [3, 6]
System Feature [Screen Shot #]
(please refer to the figure below)
A sound User Manual and good GUI
makes the product easily
understandable
Help [1], GUI Design [1-6]
Portability
Anybody can use the system via
internet and the system is nonplatform specific
Link to application:
http://hypv3355.appliedi.net/G14K
wic/
NFR3
Enhanceability
Modular Design [1-6]
NFR4
Reusability
The system can accept updates
without problems
The modules of the system can be
easily reused because of fewer
assumptions
NFR5
Good performance The system responses quickly and
Ouput [3, 4, 6]
correctly
User-friendly
The GUI design is simple to use and a Help, Clear Button [1] [2]
help function helps user
NFR6
Modular Design [1-6]
NFR7
Responsiveness
The system responses in two minutes
Ouput [3, 4, 6]
NFR8
Adaptability
The system is modular to be easily
maintained
Modular Design [1-6]
11
Global 14
KWIC WRS v1.4
The following figure is a snapshot of the KWIC system GUI annotated with references used by
the requirements to implementation traceability matrix.
12