{Wireless Internet Tutoring System}\{Design Document}

Wireless Internet Tutoring System
Design Document

Nadya Belov, Dmitriy Bespalov, Ilya Braude,
Immanuel Comer, Daniel Lapadat, Andrew Ragone

1 Introduction
    1.1 Goals and Guidelines
    1.2 Usability Testing
2 General
    2.1 Services
        2.1.1 L^AT_EX Renderer
        2.1.2 L^AT_EX Server
        2.1.3 L^AT_EX Cache
    2.2 Network
        2.2.1 Message
        2.2.2 MessageException
        2.2.3 MessageHeader
        2.2.4 Parser
3 Client
    3.1 GUI
    3.2 Network
        3.2.1 Sending Data
        3.2.2 Receiving Data
        3.2.3 Protocol
    3.3 ClientSessionManager
        3.3.1 Efficient Query/Response System
    3.4 ServiceManager
4 Server
    4.1 Session
    4.2 ServerServiceManager
        4.2.1 ServiceDescription
    4.3 User
    4.4 ServerSessionManager
5 Client-Server Communication Protocol
6 UML Design
    6.1 Client Architecture
    6.2 Server Architecture

List of Figures

    1 Top-Level System Architecture
    2 Overview of the Client Component Interaction
    3 Overview of the GUI Component
    4 witGUI Structure
    5 witForm Structure
    6 witColorPicker Structure
    7 OptionsForm Structure
    8 LatexForm Structure
    9 LaTeXButton Structure
    10 StatusForm Structure
    11 ShapesForm Structure
    12 SessionSelectForm Structure
    13 SessionUsersForm Structure
    14 Canvas Component Overview
    15 witCanvas Structure
    16 witClientCanvas Structure
    17 witShape Structure
    18 witCircle Structure
    19 witLine Structure
    20 witMultipointLine Structure
    21 witRect Structure
    22 witText Structure
    23 witTriangle Structure
    24 Client Network Component Overview
    25 Network Structure
    26 Message Structure
    27 MessageHandler Structure
    28 MessageListener Structure
    29 Parser Structure
    30 Protocol Structure
    31 Session Component Overview
    32 ClientSessionManager Structure
    33 Services Overview
    34 ServiceManager Structure
    35 ServiceDescription Structure
    36 Globals Structure
    37 StringTokenizer Structure
    38 Overview of the Server Component Interaction
    39 Server Structure
    40 Latex Cache Structure
    41 Latex Renderer Structure
    42 Latex Server Structure
    43 Message Structure
    44 Message Header Structure
    45 Network Structure
    46 Network Reader Structure
    47 Null Session Structure
    48 Parser Structure
    49 Message Protocol Structure
    50 Server Service Manager Structure
    51 Server Session Manager Structure
    52 Service Description Structure
    53 Session Structure
    54 Server Architecture

1 Introduction

The Wireless Internet Tutoring System WITS, overcomes the problems of text-based messaging by allowing for an environment where text, symbols, and graphics can be manipulated and transmitted by persons involved in the tutoring session. WITS is the integration of special software with bleeding-edge hardware available today. WITS allows a tutor to help a student while being geographically separated. It provides the tools which allow a tutor to quickly and efficiently convey his knowledge about a particular math subject to his tutee using textual and graphical representations.

This document presents the architectural design of WITS. The design outlines the high-level and low-level architecture specifying all of the objects that are necessary in WITS as well as their interaction with each other and the flow of information in the system. The architectural diagrams are presented using UML and provide detailed class headers along with several message protocols that are used for inter-component interaction. The proposed design is lightly coupled, modular and extensible. The overall architecture of WITS can be described as a client-server architecture, however, a notion of services is introduced. These services need not be specifically tailored to WITS and may be stand-alone applications that will service WITS along with other systems. The fast pace of technological advances in the world of computing demands that the design for our system be lightweight and modular.

1.1 Goals and Guidelines

In assuring that the WITS is delivered on-time and satisfies all of the original requirements specified in the Requirements Document and reinforced in this document, careful outlining of development schedules and procedures as well as testing must be implemented. In order to assure that our system will be delivered on-time, our team has established development and testing guidelines. We plan on developing our client and server components concurrently. In developing each of those components, we will implement an evolutionary model to ensure that rudimentary functionality has been established before any complex features are implemented. At the completion of each of the development phases which will include a new set of functionalities, extensive testing will be implemented to make sure that the system as it currently stands at that point can run on the chosen hardware (Treo 600) and a demonstration with a basic scenario can be accomplished.

1.2 Usability Testing

Usability of a particular system can augment the user in accomplishing a set task. In order to insure that WITS is usable by users of all skill levels (beginner, intermediate and expert), computational and heuristic usability testing methods will be employed at the final stage of testing. This effort will furthermore assist us in the creation of final documentation which will include user manuals and tutorials.

2 General

2.1 Services

Services provide the system with additional capabilities that would not be included otherwise. Reasons include CPU speeds, memory, complexity, or intensive calculations. Our client system is limited by the device that it is running on. Services allow the client to perform tasks that it otherwise would not have the power to do. An example of this is L^AT_EX rendering. The application that does the latex rendering is several Megabytes in size and would be processed slowly if rendered on the client. Services allow the clients to render the latex independently. They are autonomous and know nothing about the WITS system. They can implement their own protocols and even be distributed throughout the network or run locally. The modular design approach used in making the services and independent and non-critical components allows for a significant amount of freedom in the range of systems the WITS system can run on. If clients are on opposite ends of the world they can have their local services render the latex for them, hardware and software capabilities permitting. It must be noted that services are not limited to just rendering latex or even rendering capabilities. As our system evolves and becomes more sophisticated, so will the services that may be associated with our system that will provide WITS clients with certain capabilities. As shown in the UML diagram depicting the architecture of the WITS Server, the WitsServer object will contain a ServerServiceManager object that will be responsible for providing the services to the server. If the client, however, already knows about the available services, it will be able to use these services without accessing the WitsServer. This modular design also allow the services to provide other systems with their service. The services may have capabilities to make themselves known. Given such capabilities, both the client and server side of our architecture will be allowed to utilize these services simultaneously and independently.

2.1.1 L^AT_EX Renderer

L^AT_EX rendering is enabled through the use of services described above in Section 2.1. This object is responsible for listening for requests to render a formulae, create an image of the rendered formulae and send it back to the requesting party.

2.1.2 L^AT_EX Server

LatexServer object is responsible for creating a latex renderer described in Section 2.1.1 for each newly created connection.

2.1.3 L^AT_EX Cache

In order to further speed up processing of latex commands and image rendering as well as reduce bandwidth use, LatexCacheObject in Figure 40 is used to cache previously entered commands.

2.2 Network

The Network object sends and receives data from the network. Because of the time-critical nature of data exchanged between the server and client, our Network layer uses the TCP protocol as it's underlying transport format. TCP guarantees that data is received in the order that it was sent, and that it does not get corrupted along the way.

WITS uses it's own protocol, described in Section 5 to handle client-server communications. Translation between Java objects and our protocol is handled by the Parser (Section 2.2.4).

The Network object contains a Java Socket that it uses to communicate with the physical network. The exact Java code for establishing and maintaining a Java Socket will vary on the server and client platforms, but the function and interface are the same.

2.2.1 Message

The Message class represents all messages that are passed throughout our system. Specific instances of this class can express information such as shape additions and deletions, chat messages, and session management directives.

2.2.2 MessageException

This object is created upon the receipt of a malformed message.

2.2.3 MessageHeader

In an effort to keep a lightly coupled and extendable design, the header of the Message Object described in Section 2.2.1 contains all of the header information.

2.2.4 Parser

The Parser translates between the Message class and the WITS communications protocol. Received data gets transformed into a Message object and propagated upwards in the system. Conversely, Message objects are translated into a representation consistent with our protocol and sent through the network. See Figure 2 for a system architecture diagram.

3 Client

The client application is an intricate system designed to operate efficiently on the limited resources that are available on the Treo 600. Both CPU utilization and network usage are controlled to ensure that the system stays as responsive and functional as possible at all times. There are four components (subsystems) in the client architecture: GUI, Network, Session, and Services.

3.1 GUI

The GUI component is responsible for all of the user interaction and processing. It is also responsible maintaining the witCanvas (Figure 14) and the various witShape's that are associated with our application (see Figure 3). There are two packages that are associated with the GUI: witGui and witCanvas. The package witGui handles program initialization and the creation of all GUI components. The witCanvas package is responsible for storing various witShapes and rendering them on witClientCanvas.

It is important to note that the GUI runs in the main application thread that is also responsible for user interaction and painting the screen. Therefore, all events that are generated by the user and that must be handled by the program are handled in separate threads. This is because these operations can be time consuming, it is not acceptable for the UI to lock while the user's request is being serviced.

3.2 Network

The witNetwork package is responsible for all networking that the client application performs. At the heart of the design is the Network class. In addition to performing all the functions described in Section 2.2, the client Network class works in the following manner. The network component overview is shown in Figure 24.

For clear performance reasons, the Network class runs in it's own thread after a successful connection has been established. Running in a separate thread allows it to operate independently of the rest of the application. A Network is initialized with an IP address and port number to connect to. After the connect() method has been called, the main network thread starts which monitors the connection for incoming information, and sends data over the network in a loop while the connection is deemed to be open. Thus the two main operations of the Network class are to send and receive data.

3.2.1 Sending Data

When the Network is asked to send data to the server which it is connected to, it does not immediately do so. Instead, it buffers the request in a queue. During the execution of the Network thread, if there is data that needs to be sent out in the sending queue, all of the data in the queue is sent to the server. The queue operates in a FIFO (first in, first out) manner so that the order of messages is conserved.

3.2.2 Receiving Data

After the Network thread takes care of servicing any outgoing data, it checks the incoming connection for incoming data. If there is enough data to be able to construct the full header of a Message object available, then it is read, and consequently the rest of the Message object is read from the network. Once a Message object is read from the network and created, it is dispatched to all MessageListeners who are registered with the Network object. This is an effective way for all parts of the client application to quickly be notified of relevant messages from the server. There are two ways to register a MessageListener with the Network. One is to register a general listener that gets called for every message received. The second way is to register a MessageListener for a specific message class (see Section 5). Specific MessageListeners will only be notified if the receivedMessage is of the specified class. Thus subsystems of the application only need to handle messages that they are interested in instead of all messages that are sent by the server.

3.2.3 Protocol

The Protocol object is mainly responsible for ensuring that the login sequence is performed according to the correct protocol. This is implemented as a Finite State Machine (FSM). An FSM is a collection of states and transitions from one state to another based on certain rules. Using an FSM to implement a protocol is a defacto standard. Once the login is performed, the Protocol enters and idle state. In this state, any session-related message can be sent or received. The Protocol class implements the MessageListener interface and thus receives all messages from the network.

Note that the server updates the client whenever a significant change occurs. For example, when a new session is created or deleted, an updated list of sessions is sent to each client. The same is true for the list of users that are in the same session as the current user, and the list of available services (Section 3.4). The client handles such update messages by registering various MessageListeners (as described in Section 3.2.2).

3.3 ClientSessionManager

The ClientSessionManger is at the heart of the client's operation. It can be thought of as the glue between the GUI layer and the network layer. It also contains information about the state of the session and the server. This information includes the IP address and port of the server, the user name, and the current session that the user is in. Once the Session Manager is instantiated, it starts up the network services (Network class) and then starts monitoring the connection. Should the connection be severed, the session manager automatically instructs the Network object to reconnect to the server. See Figure 31 for diagram.

All operations go through the session manager. GUI generated events such as new shapes or chat messages are sent to the session manager. The session manager creates Message objects from the events, and passes them to the Network object which, as described in Section 3.2.1, sends the message to the server at the earliest possible time.

Similarly, when data is received back from the network, the Protocol objects call methods within the session manager to process them.

3.3.1 Efficient Query/Response System

There are times when the application should effectively block until some network request is satisfied. For example, when a user attempts to log in, the application should not proceed until a response from the server comes back to the client. This problem is overcome by the use of advanced threading techniques such as the use of monitors (in concurrent programming terminology). Continuing with the login example, observe that the login form simply calls the login() method of the ClientSessionManager. Once the session manager sends the login request to the server, it wait()'s until a response from the server is received. This causes the thread to sleep until it is woken up. When the Network object receives a response from the server, it notifies the Protocol of the message. The Protocol class, seeing that this message is a response to a login request, calls the serverResponse() method in the ClientSessionManager. This method calls notify() which wakes up the sleeping thread that issued the login request. The awoken thread checks the response code, and either allows the user to log in, or presents the user with an appropriate error message. The same technique is employed for requesting session and user lists from the server.

3.4 ServiceManager

The ServiceManager object (Figure 33) maintains a list of services available to the client. When an object cannot be serviced or rendered by the GUI and Canvas, it is passed to the Service Manager. The Service Manager tries to satisfy the request by using one of the services that are available to it. The client obtains this list by sending a special query message to the server, which responds with a list of available sessions. The output of the service or failure are returned back to the user. For an example, consider a L^AT_EX string as input. When a L^AT_EX string is entered, the latex code is sent to a L^AT_EX rendering service through the Service Manager. A PNG image is then returned back to the GUI and displayed to the user. At the moment, only the L^AT_EX service is implemented, however other extensions are easily possible in the future.

4 Server

4.1 Session

A Session objects describes a session between a tutor and several tutees. Each Session consists of a name, list of Users (Section 4.3) in the session, and a ServerCanvas object. The Session object is responsible for propagation changes from a single client to the rest of the users in the session. This object also keeps a history of all the annotations made on the canvas by all of the participants. Upon entering a session, a client is automatically updated of these changes¹. This feature is necessary to assure that a user does not loose all of their information in case of accidental disconnection.

4.2 ServerServiceManager

The ServerServiceManager handles all of the services present to the network. Only descriptive information about the services is stored within the Server - list of ServiceDescriptions. The implementation of each service is hidden from the Server. Clients can obtain information about the available services on the network from this component. The server will be able to use these services as well if that is needed.

4.2.1 ServiceDescription

The ServiceDescription object contains a host name, a port number, a service name, and a description of the service that it provides.

4.3 User

The User object holds a user name, and the Network object that the user is using to communicate with the server.

4.4 ServerSessionManager

The Session Manager handles all sessions that exist on the server. This is the object that users will initially establish a connection with before being given to a Session. The ServerSessionManager also handles the creation, removal of Sessions, the addition of users to a Session and the removal of users from a Session.

5 Client-Server Communication Protocol

The main task of the Network Component is to interpret messages from the components above it and transfer them into a message suitable for transfer across the network. This message should contain any updates, additions and deletions done to the current state of the world in the session. The message that will carry all of this information must be very flexible, modular and extensible. The message format, the protocol of which is described below, will be passed onto the network component as a string. The message will consist of the following format:

Magic String	Version Number	Message Class	Message Type	Message Length	Message Body
`wits`	`8 bits`	`4 bits`	`4 bits`	`6 bytes`	Message Length `bytes`

As can be seen from above, a concept of a magic number specified in our protocol as Magic String is used as a means of authentication to assuring that the message originated from a WITS client or server. Furthermore, a version number is used to allow flexibility in the WITS system where it may be necessary to run a client and a server that are of different versions. Each version may have more or less capabilities and needs and by specifying the version number, the server will be able to service that particular client accordingly, or vice versa. Message Class and Message Type are used to specify the exact operation and message that this particular message is used to carry. That is, for example, an update of a shape will have to have to specify that the Message Class is an update and Message Type is shape. Using these two concepts we can make the message protocol flexible enough to allow for additions and updates to the protocol without having to change the format of the message and thus allowing for multiple versions. The last two components of the message, Message Length and Message Body are used to specify the specifics that would come with the given Message Class and Message Type. To continue with the example presented above (shape update), the specific shape object description is saved and placed in the Message Body. Let us for example suppose, that the particular shape is a triangle. The Message Body would incorporate the length of each side and the angles of the triangle. The message protocol is flexible in allowing for variable length messages that can be composed of different information in the Message Body. Bandwidth is limited on the hardware platform, Treo, and it is impractical to pad some messages that will not necessarily need to be as large as others that may need to be significantly larger in size. The details of the actual identifiers used to specify the specific type of Message Class and Message Type are left to implementation and will be specified in the final documentation.