T-106.420 assignment 2 — Reactor pattern

In this assignment, you will implement a pattern commonly used in a wide range of concurrent programs including servers and graphics libraries and apply it to a simple client-server application.

Background

As a fan of the game Hangman, you want to create a networked version of the game in which multiple players can co-operate in guessing a word. Also being a fan of design patterns, you decide to use the Reactor design pattern for the game server. Basically, the Reactor pattern consists of a (Initiation) Dispatcher that dispatches events received synchronously through a (Synchronous Event) Demultiplexer from Handles to Event Handlers. Events are dispatched by calling the Event Handlers sequentially.

Task description

Your task is to implement the Reactor pattern and a simple client-server implementation of multiplayer Hangman.

Reactor

In this assignment, a simplified Reactor pattern is implemented. Events are not divided into different types (e.g. accept, input, output, close); a registered event handler will receive every message received by its handle while it is registered to a Dispatcher. Your Reactor implementation must conform to the following specification (Java source code):

All the classes below are in package reactor.

public class Dispatcher
- Implements the Dispatcher part of the Reactor pattern.
- public Dispatcher()
  - Create a new Dispatcher with no Handlers.
- public void handleEvents() throws InterruptedException
  - Waits for an event and processes it. This method is usually called repeatedly in a loop. If interrupted, this method throws an InterruptedException.
- public void addHandler(EventHandler h)
  - Start dispatching incoming events for h.
- public void removeHandler(EventHandler h)
  - Stop dispatching incoming events for h.
public interface EventHandler
- Handles events from its Handle.
- public Handle getHandle()
  - Get the Handle from which the EventHandler receives events.
- public void handleEvent(Object s)
  - Handle an incoming message/event represented by an object s, as received from the Handle.
public interface Handle
- Represents one end of a (possibly bidirectional) communications channel. Corresponds to e.g. a file handle or a network socket.
- public void write(Object s)
  - Send object s as a message on the channel. Note that Handles are not required to send or receive arbitrary objects; the supported types are determined by the needs of the application and the Handle implementation.
- public Object read()
  - Wait for a message from the channel and return it. These received messages are the events that are dispatched by the Reactor. Handle implementations may also return objects representing error conditions where applicable.
- public void close()
  - Close the channel.

Note that the above Handle and EventHandler interfaces are intended to be implemented by the application that uses the Reactor pattern. In other words, your Reactor implementation should not contain any implementations of these interfaces; instead it should behave as specified above when any Handle and EventHandler implementations compliant with the above specification (such as those in your Hangman implementation) are used with your code.

Hangman application

The Hangman application should consist of a server implementation based on the Reactor pattern and a client implementation. The server and clients run in separate virtual machines (which may be on separate physical machines). The server is given the word that is to be guessed on startup and the number of incorrect guesses needed to lose. The clients guess one letter at a time. Each time a client guesses a letter, the server sends each client a message describing the state of the guessing so far. Guessing is case insensitive; all words and guesses are shown in lower case. Clients may connect and disconnect at any time.

Players share guesses. Execution is completed when the amount of remaining attempts reaches zero. After the message describing the last guess is sent and processed, the server and all clients should be terminated. Similarly, execution is stopped if the word is correctly guessed.

The Hangman client must use standard input and output (System.in and System.out) for its user interface. When a client starts, it must connect to the server and print a line of the form:

<guessed word> <number of remaining tries>

Every time a guess is made, the client prints out a line of the form:

<guessed letter> <guessed word> <remaining tries> <name of last guesser>

The guessed word is the word to be guessed with unknown characters marked by dashes ("-").

Guesses are made by entering a line containing a single character on standard input (any extraneous characters and newlines should be ignored).

Example session for user Bob (Bob's input in bold):

-------e--- 9

o

o -o-----e--- 9 Bob

n -on----en-- 9 Alice

r -on--rren-- 9 Alice

y

y -on--rren-y 9 Bob

i

i -on--rren-y 8 Bob

c conc-rrency 8 Alice

u

u concurrency 8 Bob

Execution

The Hangman server must start by the command (assuming Java is in the path):

java hangman.HangmanServer <word to guess> <number of failed attempts>

The Hangman client must start by the command:

java hangman.HangmanClient <server host name> <player name>

The Hangman server must print the following when it can receive connections (and nothing else if everything works correctly):

Server running

Communication

You may use any of the communication mechanisms provided by the Java 1.4 SE API to implement communication between Hangman clients and servers (using TCP sockets is strongly recommended). However, note that your solution must allow communication between machines connected by an internet and should not require super-user privileges to run. You may assume that only one Hangman server is running on each host.

Concurrency and synchronisation requirements

Synchronisation should be done using the basic Java synchronisation primitives (those built into the language and java.lang, not java.util.concurrent). Inefficient solutions, such as polling and busy-waiting, will be rejected. Use of unsafe methods such as java.lang.Thread.destroy() will also lead to rejection.

Error handling

Handling errors correctly is considered an important part of proper programming style. In particular, programs that handle network connections and other forms of I/O must be prepared to handle cases where an I/O channel fails and closes without warning. The Reactor implementation described above does not specify the mechanism used to inform EventHandlers of errors in a Handle. Instead, the handle can send, for example, different types of objects as events to differentiate between normal events and errors.

Style requirements

The program should be written in clear, reasonably object-oriented Java. We will not accept programs that are hard to read, violate basic object-oriented programming principles or contain a large amount of repeated code with minor variations. Cryptic method and variable names should not be used.

Explanatory comments are required for code that is not self-explanatory to a programmer fluent in Java. However, you should not clutter your program by stating the obvious. As an example, Javadoc comments describing the syntax of trivial methods (such as accessors) will be tolerated but are discouraged.

Documentation

You must provide a PDF file in which you explain how your solution works. In particular, you should explain how your Reactor implementation converts incoming simultaneous events from different handles to a sequence of event handler calls and how the parts of your Hangman implementation communicate. The documentation should not contain a line-by-line explanation of the implementation; an explanation of the structure of the implementation is sufficient.

Language

Comments, variable and method names and documentation may be written in English, Swedish or Finnish. You should avoid mixing these languages, but you may use different languages for different aspects of the assignment (e.g. code in English, documentation in Swedish and comments in either of the two is fine).

Hints

TCP connections are probably the easiest way to implement the connection between server and client, in which case your Handles will be wrappers for java.net.Sockets and java.net.ServerSockets. To send text through a Socket, create a java.io.BufferedReader and java.io.PrintStream using something like:
```
        PrintStream out;
	BufferedReader in;

        try {
            in=new BufferedReader(new InputStreamReader(
                                      socket.getInputStream()));
            out=new PrintStream(socket.getOutputStream());
        } catch(Exception e) {
            throw new RuntimeException("Internal socket error");
        }
```
Actually sending the text is left as an exercise for the student.
telnet and netcat can be used as generic clients for TCP-based servers. This can be useful for debugging the Hangman server if your communication protocol is human-readable.
If your program gets stuck, you can get a dump of the current position of all the threads by sending SIGQUIT to the Java process (usually Ctrl+\ in Unix and Ctrl+Break in Windows).

Submission

Before the deadline (2005-12-16 03:00), you must submit a gzipped tar archive containing your solution using the form below. The archive must contain the following files:

`reactor/`	The Java source code (version 1.4 or earlier) of your Reactor implementation (the directory corresponds to the `reactor` package), including the predefined `EventHandler` and `Handle` interfaces.
`hangman/`	The Java source code (version 1.4 or earlier) of your Hangman implementation (the directory corresponds to the `hangman` package).
`description.pdf`	A PDF containing the documentation for your solution.

Your program will be compiled and run with the standard library and testing code included in the classpath.

You may work in pairs. The grading does not depend on whether you are working alone or in a pair.

Results will be sent to <student number>@students.hut.fi.

Page last updated by Jan Lönnberg 2005-11-25.