Fall 2009: CS5410 Fault-tolerant Distributed Computer Systems

Phase I: Distributed Banking System

Due: 11:59pm, 9/30/2009

General Instructions. Students are required to work together in a group having between 2 and 5 students. All members of the group are responsible for understanding the entire assignment.

No late assignments will be accepted.

Academic Integrity. Collaboration between groups is prohibited and will be treated as a violation of the University's academic integrity code.

Background: Building a Distributed Banking System

This assignment is intended to help you learn how to write distributed programs in JAVA or C#. You will program a simple client/server that employs UDP for communication. The resulting system --- a distributed bank --- will then provide a sandbox for exploration and implementation of various topics we study this semester.

Our bank comprises a set of branches. Each branch manages a disjoint subset of the bank's accounts. Associated with each account is a unique account number, a balance, as well as other information that will be of less concern to us.

Customers may invoke the following operations on accounts:

Deposit( acnt, amt ): Cause the balance of account number acnt to be increased by the specified amount amt. Returns the new account balance.
Withdraw( acnt, amt ): Cause the balance of account number acnt to be decreased by specified amount amt. Returns the new (possibly negative) account balance.
Query( acnt ): Returns the balance of account number acnt.
Transfer( src_acnt, dest_acnt, amt ): Cause the balance of account number src_acnt to be decreased by amt and the balance of account number dest_acnt to be increased by amt. Returns the new (possibly negative) account balance of account number src_acnt.

What to Build

Structure of a Branch. The branches of a real bank would be geographically separate and, therefore, each branch would have its own processor and would communicate with the other branches using some sort of network. We won't depart too far from reality, even if all branches execute on a single processor, by stipulating

that communication between branches is accomplished only by using UDP (unreliable datagram protocol), and
that each branch can directly communicate only with the subset of branches defined to be its neighbors according to the network topology.

Structure your distributed bank as follows. Implement each branch as two applications --- a branch server and a branch GUI. A branch GUI communicates (only) with its branch server, controlling its behavior; branch servers directly communicate with other branch servers.

Associated with each branch server is a single unique network address to which messages destined to that branch server can be sent; associated with each branch GUI is also a single unique network address to which messages destined to that branch GUI can be sent. (Each of these network addresses will correspond to a distinct UDP socket.) For a branch B, we write B.ServPort to denote the network address associated with the branch server and we write B.GUIPort to denote the network address associated with the branch GUI.

Inter-Branch Communication Limitations. Communication between branches is likely constrained to follow some given network topology. Therefore, construct your system to accept as an additional input the fixed, static, interconnection graph that defines which branches can send messages to which others. This graph should be input from a text file. Each line of that file should have the form

B1 B2

where B1 and B2 are names of branches; such a line in the file would assert that the network topology allows B1 to send messages to B2.

For this first phase of the project, the network topology might have uni-directional connections. Thus, just because branch B1 can send to B2 this does not imply that branch B2 can send to B1. However, you may assume that all branch servers have access to identical copies of this file, so all agree on the network topology for the system.

Simulate the limitations that the network topology imposes on inter-branch communication by writing a class that branches must use to send messages. This "wrapper" class (so named because it encapsulates network communications operations) should limit the allowed use of the operation for performing a UDP send (DatagramSocket.send in Java; UdpClient.Send in C#).

Whenever the wrapped send operation at a given branch B is invoked, the wrapper checks to see if the destination address corresponds to a branch that is directly reachable from B (by consulting the interconnection graph).

IF the destination is directly reachable THEN the real UDP send operation is invoked for the named socket.
ELSE the destination is not directly reachable; return an error-code to the invoker of the wrapped send operation.

Your wrapper class should also introduce a new operation --- whoNeighbors --- that returns the names of all branches directly reachable (along one edge of the interconnection graph) from the invoker.

Account Numbers. Assume that account numbers are of the form bb.aaaaa where bb is a 2-digit numeric value that designates a branch and aaaaa is a 5-digit numeric value that identifies an individual account within that branch. Also assume that an account comes into being (with a 0 balance) by virtue of any invocation of any operation that names that account number --- an assumption that is unrealistic but will nevertheless eliminate the possibility of operations on undefined accounts.

Client and Server: Branch GUI and Branch Server. Here, then, are descriptions of the two applications to be built.

BranchGUI creates a window on the console. This window should allow invocation of Deposit, Withdraw, and Query operations for any account managed by that branch; the window should also allow invocation of a Transfer operations involving a src_acnt managed by that branch and a dest_acnt that is managed by that branch or an immediately adjacent branch (where adjacency is defined by network topology).
BranchGUI at a branch B communicates with the associated branch server using UDP, directing messages to B.ServPort. Replies from the branch server are sent to B.GUIPort.
BranchServer receives messages on B.ServPort. Messages from BranchGUI will specify operations that the server should perform on accounts. These messages should be processed one at a time, in the sequence they are received. Operations Deposit, Withdraw, and Query are local and, therefore, reasonably straightforward. Operation Transfer need be supported only when src_acnt is managed by the current branch and dest_acnt is managed by the current branch or by a branch that is directly connected to the current branch. Ignore other Transfer operations. A supported Transfer operation can therefore be implemented by (i) doing a local Withdraw and then (ii) that branch server sending a message to B'.ServPort for the branch B' (perhaps itself if dest_acnt is local) that manages dest_acnt so that the appropriate Deposit occurs.

Note, adhering to the above specified structure (branch server, branch GUI, B.GUIPort and B.ServPort, UDP network communcation, and branch server wrapper class) is necessary so that your implementation will be usable in subsequent phases of the project.

Implementation Notes

Develop your system under Windows. This will enable your applications to use any TCP and UDP port numbers bewtween 10000 and 50000 without risk of interference with other applications sharing the processor.
Here are some helpful hints for those implementing in C#.
- Visual Studio 2005 can be run on the CSUG machines off the start menu; then select Visual C# to create a new project.
- GUI programming is really easy in C#. To create a GUI program, choose "Windows Application". GUI items can be dragged and dropped from the Toolbox, which is hidden on the left margin of the Visual-Studio IDE window.
Here are some helpful hints for those implementing in JAVA.
- JAVA in the Undergraduate Lab can be found in the path C:\Program Files\Java\jdk1.6.0_02\bin. To use JAVA, open a CMD shell and set the PATH to point to the JAVA binaries with the command
  set PATH=C:\Program Files\Java\jdk1.x\bin;%PATH%
  where x is any of 5.0, 5.0_04, 5.0_12, 6.0_2. We recommend using version 1.6.0_02. You can then run all the JAVA binaries directly from the shell.
- A GUI can be created in Java quite easily by using NetBeans 5.5 (off the start menu). Go to File on the top menu, then New File, and select Java GUI Forms in the Categories window (left) and the form type (JPanel/JFrame/etc.) in the File Types window (right). Then you can drag and drop various GUI items onto the blank form. You define the operations that should be performed when an event occurs by right clicking on the GUI item and selecting the corresponding event.
  To learn about programming of GUI and network Java applications, you will undoubtedly find the JavaSoft Java tutorial to be useful. In particular, the following lessons (or trails) should prove instructive:
  - Networking for general information on network programming in Java.
  - All About Datagrams for information on UDP.
  - Creating a GUI for how to create GUI applications.
  You will want to study carefully the discussion of UDP sockets and their communication operations: send and receive methods.

Submission Procedure. All submissions should be made through CMS. CMS provides a way for you to define your group. Be advised that each group member must take an action in creating a group, and your group cannot submit anything through CMS until the group has been created.

Submit the following files (at least):

TEAM which contains the names (and net-ids) for all team members. Also, for each team member give a 1 or 2 paragraph description of the tasks this team member performed and the number of hours this required.

README which contains

The names and a description of the contents for the other files in the directory.
Instructions for installing, compiling, and running your software on our Windows system.
A tutorial that the grader can follow to start your software and to convince himself that your system implements the required functionality. Expect the grader to spend at most 10 minutes on this task.

TOPO should specify an interesting interconnection topology for a multi-branch bank that will be used to illustrate the operation of your system.

Source files that contain the source needed to compile and run your system.

Don't underestimate what is involved in writing instructions for installing, compiling, and running your software. Do path values have to be set? Must the software be installed in a particular directory? Must the name of the host processor be put someplace? Use one group member's account to test your installation script. The easier it is to install your system, the more-kindly disposed the grader will be in evaluating your efforts.

Grading. Your grade will be based on the following elements:

Does your system satisfy the requirements on system-structure outlined above?
Does the system operate correctly?
How easy is it to follow the README file installation and sample-execution script.
How completely does the sample-execution script exercise your system.
Is the source code easy to understand and does it exhibit good structure?