Chatting AIMlessly: Building an AIM client using Java and TOC

Thomas P. Murtagh
Williams College

Summary An assignment in which students build a simple chat program that interacts with the standard AOL IM system.
String processing, loops, interactions between multiple classes.
Appropriate for CS 1.
Moderate. The program is broken down into two, one-week assignments. The first stresses strings and loops, the second involves the use of multiple classes to support multiple chats in separate windows.
1) The students implement a program similar to chat programs and text messaging systems they use constantly. They find this very motivating. 2) The use of multiple instances of classes in the second part of the project is very concrete for the students because the instances correspond to separate windows.
1) The project depends on a non-standard class, FLAPConnection, to simplify the exchange of network message between the program and the AOL server. 2) If is very painful if a campus network outage occurs during this lab!
We use the project fairly early in our course (the fourth and fifth labs). The one peculiar dependency is that our course introduces the construction of simple GUI interfaces early. Other than that, all that is assumed is familiarity with conditionals, loops, and a few string methods. In particular, we complete this lab before students have learned about arrays.
The assignment only requires students to implement basic basic chatting functionality. Motivated students can (and have) added mechanisms for displaying buddy groups, setting away messages, etc.


The goal for students working on this assignment is to implement a chat client based on AOL's TOC protocol that can interact with AOL's standard AIM system. A sample of the interface that should be provided by the program when the assignment is complete is shown below.

The program displays two types of windows. The first type provides components that can be used to log in using an AIM screen name and to start chat conversations by selecting the screen names of one's friends from a menu. We refer to this window as the control window. The window shown nearest the upper left portion of the image above is an example. The second type of window is used to chat with a single other user. The windows near the bottom left and the right side of the image above are such chat windows. Most of each chat window is filled with a scrollable text area displaying messages that have already been exchanged. The user can send a message to a friend by entering it in the text field at the bottom of the appropriate chat window and pressing the return key. A new chat window appears on the screen whenever the user starts a new conversation using the menu in the control window or when another user initiates a new chat with the user.

It is important to emphasize that students construct clients that interact with the existing and widely used AIM chat system rather than constructing their own chat system from scratch. Much of the niftiness of this assignment comes from the fact that students often start receiving messages from friends outside the lab and can respond to these messages as soon as their program nears completion. The students get pretty excited about this. Each semester students ask how they can send copies of their program to friends who do not know how to run Java programs.

Course Context

In our course, this project is broken down into two parts assigned as the fourth and fifth labs of the semester. The first part is assigned at a point where students are being introduced to writing while loops and using simple String processing operations including indexOf, substring, and concatenation. The assignment is designed to exercise these new skills. The program students complete in this first lab still provides chat functionality, but with a simpler interface. All chat messages are merged in a single text area in a single window. An example of this program's interface is shown below. In this interface, the menu in the window is used to determine the destination of each message sent rather than to start conversations.

The second part of the lab is assigned after the mechanisms required to decompose a program into several interacting classes have been introduced. In the second part of the assignment, students gain experience using classes both to generate multiple instances of an important component of their program (the chat window) and to implement an abstract interface to some of the messy data the program must process (the packets sent by the AOL server to deliver chat messages and update the list of buddies currently online).

As used in our course, this assignment depends on the fact that we introduce the mechanisms for constructing GUI interfaces and handling events associated with GUI components very early in the semester. In particular, we introduce these tools before we covers Strings, loops, and writing programs composed of multiple classes. In a course that did not present techniques for implementing a GUI, it is hard to imagine a way to define an interface that would make this assignment compelling. On the other hand, in a course that introduces GUI programming later than we do, this assignment could be restructured to provide a context in which students could practice the GUI programming skills they have acquired.

We use a locally developed library named Squint to simplify the process of introducing GUI programming. Others might teach their students how to create GUIs using only standard Swing classes or using the classes in the ACM Java Task Force libraries. In fact, the facilities provided by Squint are quite unobtrusive. Basically, rather than extend JFrame to create windows in which GUI components can be displayed, students extend a class name GUIManager which automates the installation of event listeners for many standard GUI components. As a result, the differences between the Squint versions of the solutions to these labs and the Swing versions are quite minor (about 15 lines of code). We have provided two versions of each lab handout: one designed to be used with Swing and the original handout we used which depends on Squint. In many ways, the features provided by Squint are similar to those provided by the ACM Java Task Force libraries (we completed Squint and many of our course materials before the ACM libraries were available). As a result, these lab could also easily be adapted to work with the ACM libraries.

The IM Protocols

AOL supports two protocols for sending and receiving IM messages. OSCAR, which is supposedly proprietary but has been reverse-engineered, and TOC, which is supposedly open but whose documentation requires reverse-engineering. Our lab uses TOC, primarily because all of the messages exchanged between the client and server are encoded as simple ASCII text. This makes it possible to communicate with the server using little more than the equivalent of println and nextLine methods as explained below.

The materials for the lab attached to this page address the inadequacy of the official TOC documentation by providing clear descriptions of the features of TOC required to implement a simple client. We will not repeat all of those details here, but will give a few examples to enable the reader to appreciate the kind of string processing students must do to complete the lab.

Sending IM messages using TOC is extremely simple. One simply sends the server a string with three components: 1) the code "toc2_send_im", 2) the screen name for the recipient, and 3) the text of the message surrounded by quotes. These components are separated from one another by spaces. Thus, if a user types "Hi there" in a chat window, the message actually sent to the server might look like

toc2_send_im thommurtagh "Hi there"

The server can send messages of several varieties to the client. The first field in each such message identifies its type. For this assignment, we focused on IM_IN2 messages (used to deliver chat message) and UPDATE_BUDDY2 messages (used to inform a user that one of his or her buddies has come online or gone offline). When the server sends a message to the client, the field of the message are separated using colons. For example, the message the server would send to the recipient of the "Hi there" message might look like

IM_IN2:SweetDreamer:F:F:Hi there

This example message suggests the first form of string processing required in this lab. The students must use indexOf and substring to find the separating colons and extract important components of incoming messages such as the screen name of a message's sender (SweetDreamer) and the actual contents of the message. In addition, the messages sent by standard IM clients use HTML tags to specify how messages should be displayed. The students have to write loops to remove the HTML tags so that they can display the incoming message as plain text.

Support for Network Access

AOL requires that TOC commands be exchanged between the client and server using FLAP, another AOL specific protocol implemented using TCP. We provide our students with a pre-defined FLAPConnection class to simplify access to the AOL server. FLAPConnection provides the ability to send and receive text strings through the network without knowing anything about TCP, sockets, etc.

Using FLAPConnection to send and receive message is very simple. The interface of the class is patterned after the System.out.println method and the nextLine method of the standard Scanner class. Thus, if "toAOL" is a variable that refers to a FLAPConnection, the student can send a message by executing a statement of the form

toAOL.out.printPacket( message_text );
and can receive text from the server by executing
String message =;
Through their introduction to GUI programming, our students are comfortable writing event-handling methods. The FLAPConnection class takes advantage of this by defining an event that is triggered whenever a message arrives from the AOL server. This makes it possible to implement the client without defining a separate Thread.


Extra info about this assignment: