A Collaborative Whiteboard for the Internet Classroom

The JINCS Project

Johan Anderson
Columbia University
New York, NY 10027
USA
johan@columbia.edu
Thor Denmark
Columbia University
New York, NY 10027
USA
thor@columbia.edu
Melvin Lew
Columbia University
New York, NY 10027
USA
melvin@columbia.edu

Abstract

We built an internet-based collaborative whiteboard system for hosting classes over the internet. In addition to the distributed whiteboard sketching system we oriented the project so that it offers functions useful to a classroom environment. Integrating functions useful to professors allows the teaching of students across the internet. These features include real-time management of class notes and diagrams as well as a student question manager that allows the professor to field questions and facilitates inter-student discussions. Our infracture is designed to simplify the addition of various capabilities that the professor might want such as slides, audio, video, and postscript.


Table of Contents


Introduction

This report is divided into several sections. After citing other relevant work in this field, we discuss the inspiration for our project. In the Architecture section, we go over the major modules and their design. Installation instructions and implementation details are provided in the Program Documentation section.


Related Work


Background

The growing trend in distance learning, including video courses (such as this one), makes classroom interaction difficult. One of the ways to address this problem is to utilize the Internet to enable students to participate independent of their physical location. To further this end, we created JINCS.

JINCS (Java Interactive Networked Classroom System) is a extensible platform-independent, object-oriented, multi-threaded client/server, graphical teaching environment (and it's Y2K compliant). It allows an instructor to distribute class materials, lecture, draw diagrams, and conduct discussions with students anywhere on the Internet.

JINCS is implemented in the Java programming language (jdk-1.1.5) for several reasons. Java's platform independence allows the widest possible range of students to use JINCS. The ease of implementing multiple threads in Java made it simple to create a robust and highly scalable server. The client utilizes Java's Abstract Windowing Toolkit (AWT) to create a simple to use and portable user interface.

To stay on the cutting edge, future versions of Java will contain many new features useful for collaborative applications. JINCS will be able to take advantage of these developments to add features such as postscript slides, streaming audio/video, and high resolution image distribution.


Architecture

Protocol Specification

Reserved characters in our protocol --> ':', ','
   Reserved usernames on our server --> "ALL", "SERVER"

Message protocol is --> SENDER:RECIPIENT:COMMAND
   Where SENDER is 1) a username
                   2) "SERVER" which means it's a message from the server

Where RECIPIENT is 1) a username
                   2) a comma delimited list of usernames (ie: "user1,user2")
                   3) "ALL" which is a message for the whole class
                   4) "SERVER" which means it's a message only for the server

  Where COMMAND is 1) COMMAND_NAME:ARGS

                   COMMAND_NAME indicates which command is being given (see
                   below), and ARGS is a comma delimited list of arguments
                   to the command (ie: "arg1,arg2,arg3,...").


NOTES
-----
Commands are case insensitive.

Command Arguments
Chat Commands

Syntax:

chat(message)

Description:

Sends a chat message.
messagecontents of the chat message

Syntax:

clearChatBox()

Description:

Clears the contents of the chat box.
no arguments

Syntax:

raiseHand()

Description:

Signals that you wish to be allowed to speak.
no arguments
Whiteboard Commands

Syntax:

line(x1,y1,x2,y2,thickness,r,g,b)

Description:

Draws a line on the whiteboard.
x1x-coordinate of the first point
y1y-coordinate of the first point
x2x-coordinate of the second point
y2y-coordinate of the second point
thicknessthickness of the line
rred component of the line's color
gred component of the line's color
bblue component of the line's color

Syntax:

rectangle(x1,y1,x2,y2,thickness,r,g,b)

Description:

Draws a rectangle on the whiteboard.
x1x-coordinate of the upper-left corner
y1y-coordinate of the upper-left corner
x2x-coordinate of the lower-right corner
y2y-coordinate of the lower-right corner
thicknessthickness of the rectangle's borders (value of -1 means draw a filled rectangle)
rred component of the rectangle's color
gred component of the rectangle's color
bblue component of the rectangle's color

Syntax:

circle(x1,y1,radius,thickness,r,g,b)

Description:

Draws a circle on the whiteboard.
x1x-coordinate of the circle's center
y1y-coordinate of the circle's center
radiusradius of the circle
thicknessthickness of the circle's circumference (value of -1 means draw a filled circle)
rred component of the circle's color
gred component of the circle's color
bblue component of the circle's color

Syntax:

clear()

Description:

Clears the whiteboard.
no arguments
Management Commands

Syntax:

login()

Description:

Requests to log into the server (client to server only).
handleusername you'd like to be known as

Syntax:

dupHandle(bad_handle)

Description:

Notifies that the handle you tried to log in as is already in use on the server. (server to client only)
bad_handlethe handle that is already in use

Syntax:

userList(user1, type1, muted1, host1, port1, etc...)

Description:

Server sends a list of the users who are currently logged into the server. Clients may send this command to the server (without any arguments) to request the current userlist.
user1first user's handle
type1first user's type (teacher or student)
muted1first user's mute status (true or false)
host1first user's internet hostname
port1first user's port number
etc...more users with their information grouped as shown above in sets of four

Syntax:

shutDown()

Description:

When the client sends this message to the server it means that the client is logging out. When the server sends this message to the clients it means that the server is going down.
no arguments

Syntax:

changeType(type)

Description:

Requests to change the user's type.
typetype to change to (types are currently student, teacher, and maybe observer)

Syntax:

raiseHand(true/false)

Description:

Requests to allow the user to speak.
true/falsetrue raises hand, false lowers hand

Syntax:

muteClient(true/false)

Description:

Prevents the recipient from speaking (only teachers can do this). A new userlist is distributed when this function is sent.
true/falsetrue mutes client, false un-mutes client


Protocol Semantics

Addressing Messages

Each message has a sender address and a recipient address. The sender address consists of either a username (handle) or the reserved word SERVER. Messages from the SERVER are typically system messages issued by the server itself.

The recipient address consists of either a username, a comma delimited list of usernames, the reserved word SERVER, or the reserved word ALL. When a list of usernames is given, the server forwards the message only to those users. When the recipient is SERVER, the server does not forward the message to any clients. When the recipient is ALL, the server broadcasts the message to all connected clients.

Note that usernames cannot contain the reserved ``:'', ``,'', or newline characters, nor can they be any of the reserved words described above.

User Types

Each client can be one of many types. The concept of types is useful since it allows different access levels per login. For example, in a classroom environment, students are allowed to participate in the discussion, while others may be observers only able to listen. The professor is able to distribute classroom materials to one type of user, while others (ie, auditing students) are excluded. Currently, we only utilize two types: teachers and students.

Teacher vs. Student

To support the teacher/student paradigm of a online classroom collaborative environment, the server maintains state information for each client (stored in the ClientInfo objects explained below). Each client may be either a teacher or student, have its hand raised or not, and be allowed to speak or not (mute). At startup, each student client has its hand lowered and is muted from broadcasting messages to all the clients. By default, only teachers are allowed to speak by broadcast to all of the clients, and only teachers may un-mute student clients to allow them to speak. (Note that students are allowed to send private messages to other clients at any time -- the restrictions are only on broadcast messages to all clients.)

A student client may "raisehand" in order to get the attention of the teacher client(s). The teacher client may choose to allow a student to speak to everyone by un-muting the student's client. The teacher client may also re-mute the student's client to prevent further speaking to the group.

Becoming A Teacher

At startup, a client is of type "student", only allowed to send private messages. The client provides facilities to change your user type, allowing the user to specify the type of access desired. On receipt of a CHANGETYPE message, the server updates that users type in its database and broadcasts this information to all connected clients. Currently we do not require authentication to gain teacher privileges, but this would be a simple modification to the protocol.


User Interface

When the JINCS user interface is started it presents the user with a login dialog asking for the handle that the user wants to use, the server and the port on that server to connect to. If the user correctly fills out this dialog, they are logged in.

In the upper-right corner of the control panel they will see a list of other users logged into the server. The bottom half of the control panel is the chat area of the interface where the user can see what has been said and add their own comments to the discussion. A user can send private messages to one or more other users by clicking on their names in the user list before sending their message. When the user initially logs in, they are not permitted to send broadcast messages. They must raise their hand by clicking on the "raise hand" button and be acknowledged by the teacher before they are allowed to pose a general question. The user may upgrade their status to teacher by clicking on the "become an instructor" button.

The whiteboard itself appears in a separate window. It accepts basic mouse input similar to other drawing applications provided that the user has permission to write to the whiteboard. These drawings are shared with the entire class. Below the whiteboard area are several selection boxes allowing the user to set the current drawing color, pen thickness, and pen shape.


Client

The client consists of a ClientSocket that communicates with the server, and a ClientParser which interprets incoming messages from the server. The ClientSocket uses a ClientReader thread to read incoming messages from the server and a ClientWriter thread to write messages destined for the server in a non-blocking manner. Once the ClientReader reads in a message, that message is passed off to the ClientParser to be parsed. Once the source, destination, and command is parsed out of the incoming message, the ClientParser invokes the appropriate method in the user interface.

State variables in the code keep track of the user's type, a list of users currently attending class, whether or not the client is connected, has a raised hand, or has been muted. To invoke the client, make sure that the jincs.jar archive is in the classpath environment variable and then run java whiteBoard. For further information on installation and configuration of the client, see the Program Documentation section.


Server

Overview

The JINCS Project Whiteboard Server is a robust multi-threaded networked application written in Java. Its primary function is to provide the communications infrastructure that connects Whiteboard Clients to each other. For each collaborative session, a single instance of the server is executed. Any number of clients may connect to (and disconnect from) this server at any time. This is accomplished through the use of three classes of threads: WBSListenThread, WBCListenThread, and WBCPrintThread.

Threads are essentially lightweight processes and require very few additional system resources. By utilizing threads, the server is more reliable and can handle significantly more clients than a comparable implementation utilizing forked processes. As a result, this server is scalable and can operate a large collaborative session. Of course, there are cases where this architecture of a single server supporting multiple clients is not ideal. Depending on the application, it may be preferable to use multicast or use multiple servers.

The server is responsible for maintaining information about each client, such as the hostname, port, username, type, and how to communicate to the client. Also, the server maintains the state information for the client, such as for the teacher/student model described above. Each client is associated with a ClientInfo object that stores all this information. The ClientInfo objects are then inserted into a HashTable for easy and efficient access.

Implementation

At startup, the server immediately spawns a thread called a WBSListenThread. This thread runs the entire time the server remains running. The WBSListenThread opens a socket on a user-specified port, and continually listens for client connections. Whenever a new connection is detected on the listening port, the WBSListenThread spawns a thread called a WBCListenThread to handle it.

At instantiation, the WBCListenThread creates a new ClientInfo object for the client, and inserts it into the server's HashTable. For every client connected to the server, there is a corresponding WBCListenThread that handles incoming data from that client. This allows each client to communicate independently with the server.

Whenever a message is received from a client, WBCParser is called to process the command. The WBCParser parses the command into the colon separated FROM, TO, COMMAND, and ARGUMENTS fields. It then does a caseless string match on the COMMAND field to determine how to handle the message. Some commands may require messages to be sent to clients. For each message sent to each client, a new thread is spawned that is called a WBCPrintThread.

The sole purpose of each instance of WBCPrintThread is to send a single message to a single client. As soon as the task of a particular WBCPrintThread instance is finished, the thread ends. This allows the server to simultaneously send many messages to many clients without having to wait for each client to receive its own messages. Each WBCPrintThread may need to block while waiting to write to a client, but this does not hinder other WBCPrintThread's from completing their tasks. In addition, by using synchronized write access to each client, there is no possibility for inter-thread interference in simultaneous writes to the same client.

Command Processing


Program Documentation

Javadoc documentation

Javadoc is a useful tool for generating API documentation in HTML format from code comments that are in a specific syntactic format. The JINCS Javadoc documentation tree is available at:

http://www.columbia.edu/~thor/ais/javadoc.

System Requirements

The JINCS server and clients require a java virtual machine (jdk version 1.1.5 or later, assuming backward compatibility) and enough memory to accomodate the JVM. We've tested the current version of JINCS on a Sun Ultra2 workstation running Solaris 2.6 with the jdk-1.1.5 installed.

Installation Instructions

Simply download the jincs.jar file, un-jar it into a directory of your choice, ensure that the directory you un-jar to is in your classpath environment variable as per the instructions that come along with the jvm. To run the server, type the command java WBServer [port] on the machine where you want to run the server. To run the client, type the command java whiteBoard at the command prompt.


Source Code

Source code is available.


Task List