Requirements Document

Transcription

1 Requirements Document Team B.E.E.F.E.A.T.E.R. Nick Canzoneri Adam Hamilton Georgi Simeonov Nick Wolfgang Matt Wozniski

2 Date: May 1, 2009 Date Description Revision November 25, 2008 Initial version 1 February 17, 2009 First revision 2 i

3 Contents 1 Abstract 1 2 Introduction Purpose Scope Definitions, Acronyms, and Abbreviations Developer s Responsibilities Overall Scaffold Description Scaffold Functions Overview User Characteristics General Constraints General Assumptions and Dependencies Specific Requirements Scaffold Core Client/Server Communication Sessions and Authentication Operation Library Requirements Windowing Testing Multi-Threading Support Event Handling Proof-of-Concept Applications Hearts Game Purpose Definitions Functional Requirements Use Cases Document Reviewer Purpose Definitions Functional Requirements Non-Functional Requirements Use Cases Instant Messaging Client Purpose Definitions Functional Requirements Non-Functional Requirements Use Cases Competitive Analysis 31 7 Non-Functional Scaffold Requirements Delivery Usability Interoperability ii

4 1 Abstract The goal of this project is to build a generic development scaffold which shall allow rapid development and deployment of web-based applications. This project shall consist of two major parts, an AJAXbased framework and several diverse applications to demonstrate the framework. 2 Introduction 2.1 Purpose The purpose of this document is to describe the external requirements for an AJAX development scaffold. 2.2 Scope This document is the only one that describes the requirements of the software. It is meant for use by the developers of B.E.E.F.E.A.T.E.R. and shall be the basis for validating the final delivered system. Any changes made to the requirements in the future shall be integrated into the development plan during future build cycles as the Agile development of the project continues. 2.3 Definitions, Acronyms, and Abbreviations Agile A software development methodology that encourages frequent inspection and adaptation of the design and a set of engineering best practices that allow for rapid delivery of high-quality software. AJAX Asynchronous JavaScript and XML. Using AJAX as a technique is the action of using a XML- HttpRequest to get information from the server asynchronously, meaning that the browser engine does not wait for the response from the server. Note that AJAX by design has a same-domain policy, which means that you can only send an XMLHttpRequest to the same domain that the JavaScript code is called from. API Application Programming Interface. An API is composed of the set of functions exported by a library, meant to be called by applications using that library. Client A computer or browser that requests objects from another computer (the server) over the Internet. CSRF Cross-Site Request Forgery, a type of security vulnerability that is exploited when a malicious web site causes a user s browser to perform an unwanted action on a trusted web site. CSS Cascading Style Sheets. It is a language that specifies the presentation of items. Framework A basic conceptual structure used to solve or address complex issues. The framework presented will abstract away the complex implementation details of writing web-based applications, allowing developers to quickly surmount formerly difficult problems. HTML Hypertext Markup Language. It is the primary language used for creating pages on the World Wide Web; other languages like CSS and JavaScript are meant to extend HTML. HTTP Hypertext Transfer Protocol. It is the primary protocol used for requesting web pages from a web server. JavaScript A scripting language that runs on the client. It is used to perform actions on the client and help perform requests to a server. 1

5 JSON JavaScript Object Notation. It is a data format whose main goal is data interoperability. Modal Dialog A type of dialog that must be dismissed before that dialog s parent window can be interacted with again. Modern browser In this document, the phrase modern browser is used to describe web browsers that support JavaScript version 1.7 or higher and CSS version 2 or higher. This list includes Internet Explorer from version 7 on, Firefox from version 2 on, Opera from version 9 on, Safari from version 3 on, and all versions of Google Chrome. Multi-threading The ability to run code with two paths of execution s instructions interlaced, rather than finishing one path before beginning the next sequentially. Mutex A form of execution control that prevents multiple simultaneous threads of execution over a section of code. Polling Requesting a status update. Since HTTP is a pull protocol, the applications will need to request status updates from the server by polling; the server cannot push those status updates. Polling interval The rate at which polling is done. A shorter polling interval means more poll requests per unit time, resulting in greater responsiveness for the application but more strain for the server. POSIX The Portable Operating System Interface. This is the common name for the collection of standards falling under IEEE 1003, which specify the operating system API and interfaces for what are loosely called the UNIX-like Operating Systems. Pull protocol A protocol in which the client-server query is initiated by the client. Push protocol A protocol in which the client-server query is initiated by the server. Scaffold A programming framework that runs alongside application code to assist the developer by providing functionality. Server A computer or computing system that provides services across a network. SGML Standardized Generalized Markup Language, a metalanguage in which one can develop markup languages. XML, HTML, and XHTML are examples of markup languages that are defined by SGML. State Persistent information stored across a network connection. HTTP is a stateless protocol, meaning that no persistent information is maintained between multiple requests by a user. This poses a design problem for AJAX developers, who need stateful connections. UNIX A multi-user operating system initially developed by AT&T Bell labs, upon which many of the POSIX standards are based. UNIX-like Unix-like operating systems conform to the POSIX specifications. URL Uniform Resource Locators. These are the addresses by which web pages are located. W3C The World Wide Web Consortium is the international standards organization that governs the standards used on the World Wide Web. W3C compliance means that an application complies with all relevant W3C standards. XHTML Extensible Hypertext Markup Language. XHTML is simply HTML that is written to be XML compliant. XML Extensible Markup Language, a strict subset of SGML meant to be easily machine parsed, human readable, and unambiguous. XSS Cross-Site Scripting, a security vulnerability allowing code injection using a specially formatted URL. 2

6 2.4 Developer s Responsibilities Guaranteeing the minimum number of bugs. Demonstrating functionality through the development of sample applications. Supporting the Agile evolution of the project through frequent inspections and adaptations as the project requires. Building testable code to allow verification of the code application. 3 Overall Scaffold Description 3.1 Scaffold Functions Overview At the core, our development scaffold shall alter the look of the AJAX connection between the client and server ends of applications. While AJAX is a pull protocol with spartan connection functionality, our scaffolding shall overlay a state-aware message passing connection for application developers to use. In addition, we shall provide a development library that shall add many of the higher-level extensions commonly found in modern languages. These shall include added language features, data structures, support for multi-threading, application testing, and windowing. 3.2 User Characteristics Users of the development scaffolding shall be developers of web-based applications intended for users of World Wide Web enabled systems with Internet access, including mobile devices. These developers shall be assumed to be knowledgeable in web-based programming, but need not know the specifics of AJAX programming. Developers shall be responsible for creating the server-side and client-side portions of their applications, while our development scaffold shall manage the intermediate communication and provide support. 3.3 General Constraints The client-side provisions of the application shall run on all modern web browsers, although individual application developers using the platform may make additional assumptions about the operating environment. The server-side portion of the scaffold shall operate on Unix-like platforms. 3.4 General Assumptions and Dependencies The developers shall assume that users of web-based applications will be using modern web browsers with JavaScript 1.2, AJAX, CSS 1.0, and media loading capabilities enabled. 4 Specific Requirements 4.1 Scaffold Core The scaffold core is responsible for improving the programmer s view of the AJAX connection between the client and server ends of applications by adding basic connection features, advanced connection 3

7 prioritization and reliability enhancements, and a messaging protocol for specifying requests and commands. In addition, the core should provide user sessions and request authentication to enhance security and allow the server to link independent stateless requests to persistent users and their state Client/Server Communication The purpose of connection management is to allow the development scaffold to abstract away the complexities of the network divide between the client and the server by algorithmically managing communications. This shall define the enhanced look for AJAX communications which should be provided to developers. As such, the focus shall be on sending and receiving data over the HTTP connection using the XMLHttpRequest (AJAX) object provided by web browsers, detecting and reacting to changes in connection state, and prioritizing queued communications. We shall further require an efficient eventbased architecture for higher-level applications to use when making requests or checking connection state. To accomplish these goals, the connection management shall be charged with selecting when messages should be sent to the server, maintaining information about the connection state, and maintaining a queue of messages that are in the pending, sending, or receiving states Client/Server Messaging To connect the server and the client, requests are sent from the client, and responses are returned by the server. Because AJAX is a pull protocol, all communications are initiated by the client. For this reason, messages in the connection manager should be able to handle both requests being sent by the client to the server, and regular polling messages which routinely check the server to see if the server has any data to push to the client Message Priorities To allow the connection manager to prioritize messages, each message should be assigned one of several specified priority levels (in order of descending priority): High High priority messages are sent as soon as possible. Data needed for a real-time operation would be sent as a high priority message. Normal Normal priority messages are sent whenever there are no high priority messages in the queue. Most user messages will be of this type. Low Low priority messages are sent whenever there are no high priority or normal priority messages in the queue. This sort of message should be used for operations done in the background, where the user does not directly observe the results of the message being sent. Polling Message Sent periodically when the connection is idle. This sort of message allows the server to push data to the client Message States As messages are communicated to the server, they should pass through many of several possible states. For each state, a set of actions is required to manage the connection: Waiting The message has not been attempted yet because it is queued or still being created. Sending The message is being sent from the client to the server. 4

8 Receiving The response to the message is being downloaded from the server. Received: Success The response to the message was downloaded from the server and processed without any exceptions. In addition, the server did not return an HTTP error code. Received: Error The response to the message was downloaded from the server, but the server returned an HTTP error code along with the message, or an exception occurred with processing of the message. Received: Awaiting Retry The server could not be contacted. Alternatively, the timeout period expired either before the server began to respond or between response packets in a multi-packet fragmented response. In this case, the current response is completed but the message should be attempted again later, and thus the current response is not final. Note that a partial response may have been loaded. Canceled The message was canceled before it entered the sending phase, meaning that it was never attempted. Aborted The message was canceled after it entered the sending phase but before it completed processing, meaning that a partial response may have been loaded but a complete response was not loaded Message Properties a. Each message has a unique identification number, so that duplicate requests or retries of the same request can be identified. b. Messages should be able to post the message body to the server to pass data or instructions. c. The message should know the full or partial response received from the server at all times. d. To facilitate connection state tracking, messages should record the message creation time, the time that the message entered the sending state, and the time the message was completed. Messages should also know how many retries were necessary to process the message Message Tasks Messages not only contain data, but can also perform tasks that alter the state and configuration of the message. Their tasks are: a. running the message. A message runs by creating a connection to the server, configuring the connection to meet the needs of the message, and performing the send/receive operation on the connection, updating the message state as the operation proceeds. b. canceling the message. A message is canceled by aborting any open connection to the server and updating the message state. c. maintaining a timeout interval while a connection to the server is open. The message should maintain a countdown to a timeout while communicating with the server, and should abort any server connections and mark the message in the Received Awaiting Retry state if the timeout interval expires. The timeout countdown should be reset each time any data is received from the server. d. comparing the message to another message. To facilitate relative prioritization, messages should be able to tell whether they come before or after another given message. Messages with a higher priority are sent first, and among messages with the same priority older messages are sent first. 5

9 Message Events Messages should be able to notify interested parties when they enter the Sending, Received Completed, Received Error, or Canceled/Aborted state Messaging Protocol The messaging protocol is used to encode commands and data as they are sent between client and server in URL-encoded text. The messaging protocol should be able to: a. Allow the client-side code to execute methods within the server-side code and receive the result of these methods, if there is any. b. Allow the client- and server-side code to exchange data. c. Allow the client-side code to request additional client-side code libraries, and to add the received results to the running client-side code base Connection Management Now that we have defined the requirements for an individual message between the client and the server, we can describe the tasks involved in connection management Connection Configuration a. The application developer can choose the maximum number of connections to the server which may be open at any time. b. The URL of the server application to communicate with should be known to each connection. c. A polling interval should be specified by the application using the scaffold, telling the connection management how often the server should be polled for new data. Polling the server lets the server use the pull-only AJAX connection to push data to the client, with the polling interval determining the delay inherent in pushing data to the client. Consequently, a smaller polling interval means more stress on the server, but a faster push rate for the server. d. The connection management must know what messages (if any) are pending awaiting an available connection to the server, and what messages (if any) are currently connected to the server Connection Management Tasks a. The connection management should be able to create XMLHttpRequest (AJAX) objects for communicating with the server, to help mitigate cross-browser issues that arise here. b. Connection management should create and submit polling messages to the server when the connection is idle for longer than the polling interval. c. The connection management should maintain the queue of messages waiting to be sent to the server, facilitating the addition of messages to the queue. When messages on the queue can be communicated to the server, the connection manager is responsible for removing these messages from the queue and launching the communication. d. Connection state reporting is also the responsibility of the connection management. Using the connection state information, the connection management should also choose appropriate 6

10 timeout values for communications with the server, and should make connection state reports available to the application developer Connection Events Scaffold-based applications may want to update their configuration as the connection state or reliability changes. Connection state changes are detected only when messages are processed, so the connection management should provide interested third parties with notifications when messages are completed successfully or in an error state Sessions and Authentication Maintaining State Across Requests with Sessions On the server side, HTTP requests are stateless, meaning that no persistent information is maintained for a single user across multiple requests. This is not desirable for an AJAX application, in which a user may be making many frequent HTTP requests and relying on the server and client to have a synchronized view of the application state. Thus, if we want to build web-based applications, we need to implement a concept of server-side user sessions to provide stateful requests over HTTP Session Management On every HTTP request, session management should: 1. Check whether the current user has a previously established session. If the user has no session, a new session is created. 2. Associate the user s request with the data stored in their session. 3. Allow all application code working on handling the request to access and modify the session data for the request. Session data is to be maintained between requests, thereby providing storage for persistent state information. If session data is not accessed for the period of an application-configurable timeout (also known as a sliding-scale timeout because the timeout resets each time the data is accessed), then the user can be assumed to have ended the session and the user s data is removed to release the storage Session Security Because sessions are used to maintain authentication and user data, the information stored in the session state may be sensitive. Therefore, it is important that user sessions are keyed to each user s specific network connection. This prevents an unauthorized user (on a distinct network connection) from being able to access the server using a falsified session identifier, thereby gaining access to the authorized user s data and privileges. Tying sessions to a user s location on a network implies that sessions are not mobile and do not move with the user. In addition, sessions are temporary and are removed whenever the user leaves the application. If sensitive user data needs to be maintained, or if the user needs access to data from multiple locations, auxiliary storage and independent authentication (such as a user name and password) should be added by an application developer. User sessions serve only to maintain temporary, connection-oriented state. 7

11 Request Authentication AJAX has a same-domain policy, meaning that requests to a server can only be made from JavaScript code loaded from a server in the same domain and sub-domain as the request. However, any user can make an HTTP request to an AJAX handler from any location, circumventing the web application. These types of requests can be used by malicious attackers to issue commands or attempt to retrieve data. One form of attack, known as cross-site request forgery (CSRF), attempts to trick authenticated users of an application into making these requests, usurping their privileges to manipulate data. In other attacks, spammers use these requests to generate or upload spam content. Thus, it is essential for application security to verify that all requests made to the AJAX scaffolding using the messaging protocol originate from a legitimate client-side application. Because applications may also occasionally exchange sensitive data with the server, it is important to mark each request based on whether it originated from an SSL-secured channel, thereby allowing application developers to require a secured channel when needed Operation Message Processing Flow To clarify the requirements for message processing, let s look at the processing of a sample message: 8

12 1. A message is created and configured by the client-side application. Alternatively, the connection management may create the message as a polling message. 2. The request (data and commands) to be sent to the server are encoded using the messaging protocol. 3. The message is added to the connection management s queue. 4. When the message becomes the highest priority waiting message and a communication slot is available, the connection management initiates the send/receive sequence on the message. 5. The server reads the request, authenticates it, and attaches the user s session data. 6. A response is created by the server. 7. Any waiting data that the server wants to push to the client is attached to the response, and then both are encoded using the messaging protocol and sent to the client. 8. When the receive phase is completed on the client-side, the message is removed from the connection management. 9. The server response is read from the messaging protocol and acted upon. At steps 3 and 9, message events allow interested parties to know about the changes to the message state. At step 8, a connection management event lets interested parties know about changes in the connection state Performance Impact Client to server connections in AJAX applications can be disruptive to real-time performance simply because of typical network lag on the HTTP connections. As a result, it is critical that message creation and processing during connection management activities be as rapid as possible to avoid incurring additional delays. Under typical conditions, message creation and connection management should take no longer than 10ms of processing time, even when the queue size is large. Likewise, attaching a user s session to a request on the server-side should take less than 10ms to allow for rapid turnaround of messages. In addition, if the client to server connection is permanently dropped while the application is running, messages may remain in the queue indefinitely due to repeated timeouts. As a result, it is necessary to limit the message queue size, to prevent the queue from growing indefinitely and gaining an unacceptable memory footprint Performance Across Platforms Because the security and language requirements for AJAX connections vary by platform, the connection management shall need to manage these differences. In addition, the above performance requirements should be met in all modern browsers, even though different JavaScript engines may have different performance profiles. 9

13 4.2 Library Requirements Windowing Windowing Definitions Window A window can be viewed by the end-user of the website as a child of the browser. This window is independent of the main webpage area, and is customizable by the developer for his ends. Title bar The top section of the window. Only thing allowed in this section is optional text for the title of the window. Button A button in the context of B.E.E.F.E.A.T.E.R. windows is the sort of button created with the HTML <button> tag, which has two important attributes. Text This is the text displayed in the button, what the user sees. Value What the button returns when it passes its data back to a function Windowing Features The B.E.E.F.E.A.T.E.R. windowing system shall allow dialog windows to be created within the page via a JavaScript call. The various window attributes can either be specified at the time the window is created or modified through further JavaScript calls in the future Window Attributes parent, the window of which this new window shall be a child container, the DOM element which this window shall be contained within title, the text that shall be displayed in the window s titlebar id, a unique identifier for this particular window classes, one or more CSS classes that this window shall belong to Attributes controlling window size width, or horizontal size height, or vertical size Attributes controlling window position relative to its container top, the offset of the top of the window from the top of the container bottom, the offset of the bottom of the window from the bottom of the container left, the offset of the left side of the window from the left side of the container right, the offset of the right side of the window from the right side of the container draggable, the window can be moved by dragging the mouse during a mouse down event on the titlebar of the window resizable, the window can be resized by dragging the mouse during a mouse down event on the window border collapsible, the window can slide to cover or uncover certain components maximizable, a button shall be added to the window titlebar that shall cause the window to toggle 10

14 between its current size and the full width and height of the page minimizable, a button shall be added to the window titlebar that shall cause the window to be collapsed and the titlebar to be resized and moved to the bottom left of the page modal, this shall be a modal dialog Window Methods collapse, behave as though a collapse button were pressed maximize, behave as though a maximize button were pressed minimize, behave as though a minimize button were pressed hide, make a visible window invisible to the user show, make an invisible window visible to the user Returning a Value If specified, the developer can assign a callback function that the window shall send data to when certain events complete. A callback function can be assigned to all of the normal JavaScript events and the window specific events described below Window Events on close, when the window is closed. on open, when the window is created. on move, when the window is being moved or dragged. on resize, when the window is being resized. on maximize, when the window is maximized. on minimize, when the window is minimized Assigning a return action A return of an event specifies what data gets returned, the value, and when the data gets returned. return value What the window returns can be specified on window creation or at a later date. To specify a return value, the developer would use an ID of an element or a class of element. The value is returned as an JSON object. return event This specifies on what action the return value gets sent. This could be on close, on keypress etc. When this event fires, whatever values specified in the return value should get returned Generic Windows The scaffold shall have the ability to create preformed windows that perform certain generic functions that would be useful in common cases. OK / Cancel Window This window has 3 components. The message and an OK and Cancel button. Clicking on either of the buttons should close the window and send the value of the button back 11

15 to the creator function. Message This is a string that displays a message to a user, detailing why this window was displayed. OK button This is a button with the text of OK and should return the value of OK when it is clicked. Cancel Button This is a button with the text of Cancel and should return the value of Cancel when it is clicked. Button+ Window This is a window with a message text and one or more buttons. The buttons are specified as a JSON object with the text and return values specified. Time Picker Window This window should display the information necessary to choose a specific time. Options when creating this window are 12/24 hour time and a set timezone time. This window should close on hitting a button in the window and should send the time information back to the function. Items in this window: Timezone Hour Minute Second - optional AM/PM - 12 hour only Finish button - when clicked should return the data Cancel button - when clicked should send back nothing Date Window This window should display the information necessary for the user to choose a single date. This window should close on clicking a button in the window and should send the date information back to the function. Items in this window: Year Month Day Finish button - when clicked should return the data Cancel button - when clicked should send back nothing 12

16 Date+ Window This window should display the information necessary for the user to choose one or more dates. This window should close on clicking a button in the window and should send the date information back to the function. A specific number of dates can be specified on creation or the user can enter as many dates as he or she chooses. There shall be several fields whereby one can pick a year, month, and day, as well as a Finish button that should return the data and a Cancel button that should return undefined. 13

17 List Window This window should display the information necessary to sort, add, or subtract items from a list of items. The items to be sorted are specified by an array. This window should close on clicking a button in the window and should send the user modified list of items back to the function. Items in this window are: Array of user modified items. Finish button - when clicked should return the data. Cancel button - when clicked should send back nothing. The image below shows the list window when the user first sees it: 14

18 The image below shows the list window after the user modifies it: Progress Bar This window shall portray a graphical display that indicates the status of an event or action of the user or application. This is accomplished with a graphic that denotes one location as start and another location as finish and as the actual status updates, so does the status portrayed in the progress bar. The developer is able to specify a callback function on the event the progress bar is modeling in order to update the progress. Items contained in this window are: The graphical display of the progress bar. The current percentage of the progress bar. Slider Window This window shall display a graphical interface to the user choosing a value that is within a number range. This is denoted by graphical elements similar in nature to the well known scroll bar. Options when creating this window are: 15

19 Beginning range value. Ending range value. Starting value of the slider. Orientation (horizontal or vertical). Predetermined values. For example, if the starting and ending values were 0 and 100, the developer could wish that only the values of 0, 25, 50, 75 and 100 would be available to choose. The other option would be to allow any real number in the range of the starting and ending value. Other items contained in this window shall be: A label containing the starting value. A label containing the ending value. A textbox containing the current value indicated by the slidebar. The graphical element of the slider Non-Functional Requirements Usability 1. The windows shall be presented in a manner that is consistent with the windows displayed within the browser and major operating systems Standards 1. The windowing library shall produce code that complies with XHTML Strict standards. 16

20 4.2.2 Testing To allow for robust application development on our application scaffold, we should also provide a testing framework for client-side code. This is intended both to support the testing of the scaffold client-side code and to allow application developers to test their client-side code. The testing framework should allow a developer to: a. Write unit testing functions that can be identified as testing code. b. Perform, within unit testing functions, test runs of program methods and validate that the test results return the expected values. c. Run all of a program s testing functions and view a report Test Reports When testing functions are run, a report should be generated detailing the outcome of all of the tests. The report should include: a. The expected return value and actual return value of each test function call. b. Whether each test function call returned an expected value. c. The overall number of test function calls that returned an expected value and the overall number that did not. d. Whether all tests were successful, or whether any failed to return an expected value Multi-Threading Support A multi-threading library shall be provided to expose basic multi-threading functionality to the developer. This library shall meet the following functional requirements: 1. Provide a semaphore data structure - A semaphore data structure provides the ability to restrict access to a shared resource. 2. Provide the ability for a thread to yield. - Provide the ability for a running thread to stop running and allow other treads to run on the CPU. 3. Provide the ability for a thread to join on a thread. - Allow a thread to stop running and wait for a specified thread to finish. When the thread finishes then the waiting tread is allowed to run. An exception in this case would be if a timeout is specified. Then the waiting thread is allowed to run after the timeout has expired. 4. Provide the ability to list all unjoined threads Event Handling JavaScript does not provide facilities for creating and utilizing event handlers by default. To add these features, we shall provide facilities for: 1. Registering event handlers to be called when an event occurs. 2. De-registering event handlers by removing them from the collection of registered event handlers. 3. Signifying an event by launching all of the registered event handlers, if there are any. 17

21 5 Proof-of-Concept Applications To demonstrate the usefulness of this development scaffold, we shall present some sample web-based applications that shall use the features of our framework. 5.1 Hearts Game Purpose The purpose of this application is to provide a multi-player Hearts card game. Using the dialog box and image functionality provided by the B.E.E.F.E.A.T.E.R. framework, this shall allow several users to play competitively against each another in a game of Hearts over the World Wide Web Definitions AI Artificial Intelligence - in this context, the ability to have a computer play the game by the rules against human players. Room A room is a listing of tables that a player can sit down at to play a game. Seat A seat is a location at a table where a player can sit to participate in the game. Table A table is the playing space for a game, with multiple seats arranged around it Functional Requirements Essential Features 1. Multiple people shall be allowed to connect to the server and join a table together. 2. Players shall be allowed to sit down and stand up from virtual seats before the game starts and after it ends. 3. Players shall not be allowed to sit down or stand up from virtual seats during a game. 4. Each game shall have a deck of cards with a known composition of cards associated with it; those cards shall be the standard cards in a 52 card poker deck. 5. Cards from the deck shall be dealt at random to all players. 6. Each player shall be able to see his own hand, as well as the cards currently in play. 7. Allow players to take turns playing a game of Hearts, ensuring that each card played is valid. 8. Only the player whose turn it is shall be allowed to play a card. 9. Players scores shall be tracked throughout the game. 10. The players shall be informed of the final scores when the game ends Additional Planned Features 1. The creator of the table shall be able to force a player to stand up from his seat. 2. Cards shall be able to be passed between players after the deal, as per Hearts rules. 3. User accounts shall be supported, and users shall be able to log in to the system with a user name and password. Unauthenticated users shall still be able to play using guest accounts. 18

22 4. Statistics for authenticated users shall be tracked over time. 5. Players at the same table, or in the same room, shall be able to chat with one another. 6. Multiple tables in a single room shall be supported, allowing multiple simultaneous games to be played. 7. Cards shall be played by clicking and dragging them Wishlist Features 1. Multiple card games should be supported, allowing a user to first choose a game to play, then enter that room and choose a table. 2. A Friends List should be supported, so that users can keep track of what games other register users are playing. 3. An options dialog should be available, allowing the user to choose which rules variants shall be used and allowing users to play with many different rule sets. 4. Computer players should be available, with AI allowing them to play competitively against the human players. 5. Players should be able to leave the game mid way through, allowing either another player or an AI to take over for them for the remainder of the game Use Cases Playing Area The playing area for the hearts game shall resemble the below illustration: 19

23 Options Dialog The game shall provide an options dialog allowing the user to change various rules of the game, allowing each game to be set up for a particular rules variant. 20

24 5.2 Document Reviewer Purpose The purpose of the document reviewer application is to provide an area for members of a team to focus collaboration on a particular document and be able to track and view suggestions for changes to the document Definitions Session A specific instance of the document reviewer application. Identify user/ Log In The action of a user providing their credentials to the system so that they can be authenticated Functional Requirements Essential Features 1. In order to create a session, a user should first authenticate himself, creating an account first if necessary. 2. The session creator should be able to upload the document to be associated with a session. 21

25 3. The session creator should be able to invite other users to join the session via identifying their addresses. 4. If an invited user is not already registered with the system, identification credentials shall be created automatically and sent to the user. 5. The session to be created shall be added to the list of available sessions for each invited user. 6. The session creator should be able to remove or uninvited members at any time. 7. Invited members should not be able to remove other members. 8. A newly authenticated user shall see a portal page detailing what sessions are available to him. 9. Clicking on a button on the portal page containing the name of a session shall make that session active. 10. The portal page shall display session metadata, such as the time of the last modification and number of current viewers. 11. A session shall contain one or more windows detailing information to the user. 12. Windows shall be resizable. 13. Windows shall be moveable. 14. Windows shall be closable. 15. Windows shall be collapsible. 16. The document window shall show the text of the document. 17. The document window shall show highlighted areas which indicate that a user created comment is attached to that portion of the text. 18. When the highlighted area is clicked, the user created comment shall be overlayed on the document window. 19. The chat window shall show the communications between members of the session. 20. Chat communications shall be prefaced by name and time. 21. Any user shall be able to suggest changes to a specific part of a document in the document window. 22. User-suggested changes shall appear as chat bubbles to all users of the session. 23. Suggested-change chat bubbles shall identify the comment, commenter, and time/date of the comment. 24. All users shall be able to communicate with other members of the session via the chat window. 25. The application shall save the comments and changes to the document indexed by time Additional Planned Features 1. Mousing over a session s modification time in the portal page should display a snippet of the actual modification and its author. 2. Mousing over a session s user counter in the portal page should display the names of the current viewers. 3. Users should be able to expand and collapse session identifiers in the portal page in order to view extra information about the session. 22

26 4. The session creator shall be able to modify the text of the session document. 5. The session creator shall be able to notify logged in session members of changes to the document. 6. The session creator shall be able to remove user created comments. 7. The session creator shall be able to remove a users session access on a temporary or permanent basis. 8. The session creator shall be able to focus the document window of all logged in session members on a particular portion of the document text. 9. Users shall be able to view only the comments of the document Wishlist Features 1. The portal page should provide a method for users to sort or tag sessions. 2. Window size and position shall be saved as a preference for the user. 3. Lines containing comments shall be identifiable by a colored area on the side of the document window. 4. Users shall be able to filter comments based on author. 5. Users shall be able to filter comments based on page section Non-Functional Requirements Product Usability 1. The application shall be W3C compliant Organizational Standards 1. The application shall produce code that complies to XHTML Strict standards Interoperability: 1. The application shall be usable in all modern web browsers Use Cases Session Creation A dialog window similar to the figure below shall be presented in order to allow an authenticated user to create a new session. 23

27 Logged In / Portal Section This section of the application is what the user sees after they have authenticated themselves to the application, and before they have chosen a session to join. 24

28 Within a Session After choosing a session to join on the portal page, the user shall be presented with a session page resembling the figure shown below. 5.3 Instant Messaging Client Purpose The purpose of this application is to provide an instant message service to users of the application. This application shall achieve its goal through use of dialog boxes using the beefeater framework. 25

29 5.3.2 Definitions Chat Window A movable, resizable frame containing the text box and the view box Text box A box contained in the chat window that is able to be typed in by the user. Items typed into this box are only seen by the originating user. Hitting the <Enter> key while the cursor is in the text box shall send all non-empty strings in the text box to the view box. View Box The box which all viewers of the conversation are able to see. This box shows the messages sent by all members of the conversation, and reflects state changes of members of the conversation. Conversation The sending and receiving of messages in a chat window. Members of a conversation The two or more users sending and receiving messages in a chat. inviter A user who invites others to a chat. invitee A user who gets invited to a chat Functional Requirements Essential Features 1. The application shall send and receive plain text messages. 2. A user shall be authenticated by using a user name and password. 3. A user s authentication user name shall be used as his screen name. 4. One on one chat shall be supported, allowing a user to send and receive messages with one other user that is currently using the application. 5. Chat rooms shall be supported, allowing a user to send messages that are visible to all other users in a chat room. 6. A list of all users in a chat room shall be displayed to all users in that chat room. 7. A buddy list window showing online and offline users, and user status for online users, in a separate dialog box from chat and message windows shall be available. 8. There shall be the ability to set a status of available, away, invisible, and offline. The available and away states shall allow a text status message to be set. 9. A URL identification system shall be supported, such that when a URL is identified in a plain text message it will be made into a link. 10. The client shall make use of multiple dialog boxes. Each message box and chat shall be a separate dialog window, and the buddy list dialog box shall be a separate window from the messages. 11. A user shall be able to login without registering a user name using a guest account. After the user logs out the guest account shall be deleted. If Planned Feature 4 is implemented then users of guest accounts will be unable to communicate with Oscar or Jabber users. 12. A user shall be able to create a new user account for the application Additional Planned Features 1. Users shall have the option to log sent and received messages to a log file that will be made viewable and downloadable by a user of the system. 2. Users shall be able to group the buddies in their buddy list into groups using drag-and-drop. 26

30 3. Users shall have the option to be notified when a chat partner receives a message that they have sent. 4. Users shall be able to chat with users of the Oscar or Jabber protocols as well as other users of this instant messaging system. 5. Tabbed windows shall be made available, allowing users to group related conversations in a single chat box with multiple tabs. 6. The server shall be able to store messages that were sent to a user when he was offline and deliver them when he comes online again Wishlist Features 1. Users should be able to send a file from one user to another through the instant messenger. 2. Users should be able to associate a 50 by 50 pixel picture with a buddy Non-Functional Requirements 1. Messages shall be sent and received in real time. This is defined by 2-3 seconds between the time the message was sent by one user and the time it was received by another. 2. The buddy list shall show changes to a buddy s state within 5 seconds of that buddy state change. For example, a state change could be a user coming online or a user going away. 3. The application shall have a professional look. This is defined by the interface appearing orderly and well designed, and dialog boxes not being cluttered Use Cases Creating an account and registering a user name A dialog shall be presented to allow the user to create and register a user name. 27

31 1. Allow the user to enter a user name and password. 2. Create an account for the user and proceed to the connection step using the given user name and password. Exceptions If the user name the user requests is already taken, notify the user and ask them to choose another user name. If the password the user provides is less than 6 characters, notify the user and ask him to pick a better password Connecting to the service A dialog shall be presented to allow the user to authenticate with the application. 1. The user is asked to identify himself by his chat name. 2. The user should present the user name and password of an existing account, choose to log in as a guest. 3. The user s buddy list loads and he now has the ability to take part in conversations and group chats. Exceptions If the user does not provide valid credentials for a non-guest account, notify the user and ask for different credentials Starting a chat with another user 1. The user selects another user from their buddy list by double clicking. 2. If the selected user is available, a conversation window appears on both user s screens. Exceptions If the selected user is no longer online, notify the selecting user. If the selected user is in the away state, display his status at the top of the conversation window. To initiate a conversation with a user not on a buddy list, allow users to enter a user name as an 28

32 alternative to selecting a user from the buddy list Creating a group chat A dialog shall be presented to allow the user to chat with other users. 1. The user opens the Conversation menu by left clicking it. 2. The user selects the Create a Chat option from the opened menu by left clicking it. 3. A dialog box opens up asking for a name for the chat room. 4. After a user enters a name for the chat room and clicks the OK button, a chat room is created and a chat dialog box is then created and displayed. Exceptions If a chat room with that name already exists then an alert is raised to the user and name is not accepted. The user is returned to the dialog box asking for a name of the chat room. 29

33 Inviting other users to a chat 1. The user selects another user from his buddy list by single clicking 2. The user then brings up a right click menu by right clicking. 3. The user then selects the Invite to chat option by left clicking the option. 4. A dialog box opens up with a list of chat rooms the user is currently in. 5. The user then selects the chat by left clicking, then left clicks a button called invite. Exceptions If the selected user is no longer online, notify the selecting user Receiving a chat invite 1. A user is notified that another user as invited him to a chat and gives him the option to ignore the request or accept the invitation. 2. If the user clicks the accept button, then a chat dialog box displaying the chat room that the user was invited to opens. Exceptions If the invitee clicks ignore then the user doesn t enter the chat and no notification is sent back to the inviter. If the invitee is already in the room, the invite alert is not displayed Conversation A dialog shall be presented showing the current conversation. A conversation defines the sending and receiving of messages between the connected end users of the session. 1. Text typed into the text box of the chat window is what shall be sent to the other user when the sender hits the <Enter> key 2. The message shall then appear in the view window of the chat window on both of the 30