Description
1 Introduction
This lab assignment serves as a first exercise towards building distributed systems. You will be implementing a
simple Broker system which provides stock quotes to users. Work on this assignment should be done in teams. A
team should have no more than two people.
In this assignment, you are required to use the ug workstations in the GB 243 lab. You need basic knowledge
of Java to implement the assignment requirements. To help you, we are providing a ECHO server as an example. It
is recommened that you understand the ECHO example and use it as a template to build your implementation of
Broker.
The code and starter files are placed on the ug machines, at /cad2/ece419s/ referred as ${ECE419_HOME}. The
source code for the ECHO example is placed at ${ECE419_HOME}/labs/lab1/echo/. Starter files for the Broker
implementation are under ${ECE419_HOME}/labs/lab1/broker/. The Makefile and sample scripts are already
configured to use some Java paths. However, there is nothing specific to this Java version that the code (including
our sample code provided to you) requires.
NOTE: If you plan to run the code on your home machine, you will have to update the path to
Java (i.e. ${ECE419_HOME} and ${JAVA_HOME}).
1.1 Grading
This lab assignment represents 6% of your final grade for the course and is due by Monday, January 28th 11:59
P.M. It consists of three parts. Each part is graded according to the following scheme:
• Full credit for having all components of the part working according to the objectives.
• 80% if your program has a minor functional or logical mistake.
• 40% if your program is partly working but has several or major functional or logical mistakes.
• Otherwise, 20% if the code compiles successfully. To receive this credit, your code has to show “reasonable
effort” towards the objective of the lab part and any compilable code will not award you this credit 🙂
Each lab part consists of one or more client-server sessions. The user issues appropriate “commands” at the
client side(s) and then receives a response according to success or failure of the command. You can assume the
user enters the commands in the right format. Sample scenarios are provided for each part. Some Makefile and
wrapper shell scripts are provided for you for each part which are organized under broker1, broker2 and broker3
respectively. You must not use any “hardcoded” host name, port number or other configurable parameter within
your source code or the shell scripts. Such parameters have to be provided as command line parameters instead.
See the content of each shell script to learn about such parameters.
Important Note: You are free to develop your code on other platforms but you MUST “compile and test”
your work on ug facilities of GB 243 lab. Your Makefiles and shell scripts have to be properly setup for each
part and unused files removed from the submission directories. The Windows users have to pay extra attention to
compilation and test of their work as sometimes their working source codes would not compile on ug because of the
differences between Unix and Windows text file formats.
2 Part 1 – Broker Assisted Stock Quotes
2.1 Objectives
You are required to build a Broker server, OnlineBroker, that serves quotes to clients. The interface is a simple
request-reply protocol where the client provides the stock symbol and the OnlineBroker responds with the current
stock price.
2
We provide the BrokerPacket class as the packet format of the messages exchanged between the clients and
brokers. The same class (BrokerPacket) will be used for all three parts of the lab and you are not required to
change it further. Therefore, there may be certain members of the packet that you don’t use for each lab part.
The BrokerPacket class has been heavily commented to aid you in your lab. Use this as a guide.
The client obtains the symbol from user input, queries the OnlineBroker, and outputs the result. Here the user
command is simply the stock symbol. The client reflects its readiness for accepting a new command by prompting
’>’. A typical session is as follows:
[user@ug145 part1]% sh ./client.sh ug55 8000
Enter queries or x for exit:
> MSFT
Quote from broker: 28
> SUNW
Quote from broker: 5
> ORCL
Quote from broker: 16
> ATY
Quote from broker: 0
> x
[user@ug145 part1]%
2.2 Implementation Notes
OnlineBroker stores the mapping between the symbols and their quotes in a plain text file. The following is an
example:
MSFT 28
CSCO 13
ORCL 16
SUNW 5
INTC 18
When a quote is requested from the client, the OnlineBroker does a table lookup from the file (or alternatively
from its buffer caching the contents of that file), and returns the current quote for the requested symbol. The
requested symbols are not case sensitive. In this part, we ignore all error handling details. If a symbol cannot be
found, OnlineBroker simply returns 0.
2.3 Grading
The weight of this part in the overall Lab 1 grade is 20%. In the ECE419 directory (${ECE419_HOME}), we have
provided some relevant files to you. These include a sample Makefile, as well as the shell scripts we use to launch
the client or the server (client.sh and server.sh, respectively) for testing your code. Each of these shell scripts
will launch your Java code and pass all the required command line parameters, which are passed to the shell script,
down to your Java code. You should name the main class of your client and broker codes according to the content
of each script, i.e., BrokerClient.java and OnlineBroker.java. The provided nasdaq file is the table of quotes
for OnlineBroker.
3 Part 2 – Online Brokers and Stock Exchanges
3.1 Objectives
Your goal in this part is to extend the basic client-broker relationship implemented in the previous programming
assignment, and add a stock exchange, which is referred to as an exchange from now on, to the system. The
3
exchange is responsible for contacting the OnlineBroker to add recently IPOed symbols, remove delisted symbols
and update the quote for a specific symbol which are respectively done through add, remove, and update user
commands. In this part, you also add error handling according to the errors defined in BrokerPacket.
3.2 Implementation Notes
Errors aside, it should be straightforward to extend the system since the exchange is just another client to the
OnlineBroker. There are three types of errors that we are interested in: InvalidSymbol is used when the symbol is
not found. QuoteOutofRange is used when the exchange tries to update with an out-of-range quote (assume the
range is [1, 300]). SymbolExists is used when the exchange tries to add an existing symbol to the broker. The
challenge here is to properly handle the errors in the client and output the errors to the user. Note that the content
of symbol/quotes file, i.e., nasdaq, has to be updated when the OnlineBroker exits.
3.3 Grading
The weight of this part in the overall Lab 1 grade is 40%. When grading your submission for this part, a client and
an exchange will be started on different machines.
The exchange will try to update, remove and add symbols via simple commands, such as:
[user@ug145 part2]% sh ./exchange.sh ug55 7777
Enter command or quit for exit:
> add EMC
EMC added.
> update EMC 4
EMC updated to 4.
> add SUNW
SUNW exists.
> remove SUNW
SUNW removed.
> update SUNW 19
SUNW invalid.
> remove SUNW
SUNW invalid.
> update MSFT 709
MSFT out of range.
> x
[user@ug145 part2]%
The typical session at the client would be:
[user@ug146 part2]% sh ./client.sh ug55 7777
Enter symbol or quit for exit:
> EMC
Quote from broker: 4
> MSFT
Quote from broker: 28
> SUNW
SUNW invalid.
> x
A quote for EMC is obtained after the update is issued from the exchange, and SUNW is invalid since SUNW
is removed previously by the exchange.
4
Similar to the previous part, a Makefile, an initial symbol/quotes file, and shell scripts are provided for you.
Name your exchange’s main class BrokerExchange and use exchange.sh to execute it.
Please note that the file nasdaq should be copied to your working directory so that it is writable by the
OnlineBroker. Any changes made during a session should then be reflected in the nasdaq file.
4 Part 3 – Online Stock Quotes System
Client
NASDAQ
Broker
TSE
Exchange
Naming Service
NASDAQ
Exchange
TSE
Broker
Updates
Updates
Register
“nasdaq”
Register
“tse”
Lookup
“nasdaq”
Lookup
“tse”
Local “nasdaq”
1
2 Query
“rim”
3
Forward
“rim”
4
Quote
“28”
5 Quote “28”
Figure 1: An Online Stock Quotes System
4.1 Objectives
In this part, you are challenged to implement a relatively complete online stock quotes system. The enhanced
system is illustrated in Figure 1.
The online stock quotes system consists of two stock exchanges, the TSE exchange and the Nasdaq exchange,
and two corresponding brokers, the TSE broker and the Nasdaq broker. The client does not know about the
locations of the brokers. It uses a naming service, and looks up the broker by their names, i.e. nasdaq and tse.
The client then sends its queries to its local broker (which may be the TSE or Nasdaq broker, since the client may
move). The local broker may be changed via a local command.
You have implemented much of the system in Part 1 and Part 2. In this part, we are making the system complete
with support for query forwarding. Figure 1 shows an example. First, the client connects to a broker by issuing the
“local” command. For example, let us assume that the client connects to Nasdaq. When the client issues a query
for “rim” to the Nasdaq broker, the broker receives the request, and looks up the symbol in its local list of symbols.
If a quote is obtained locally, it is returned to the client. In this case, “rim” is not found since the stock is listed in
the TSE exchange. If the symbol is missing (when we previously returned an InvalidSymbol error in Part 2), the
broker tries to look up the symbol in the other broker (in our example the TSE broker), and sends the result back
to the client. In this case, the first broker that the client contacts is both a server (by serving the client) and a
5
client to the other broker. The forwarding complexity is transparent to the client who eventually receives the result
without knowledge of which stock exchange the symbol is listed in.
With respect to the updates, for simplicity we may assume that each broker only receives updates from a single
stock exchange of the same geographic location, e.g., the Nasdaq broker receives from the Nasdaq exchange. The
exchanges are clients to the brokers, and they also need to resolve the names of brokers via the naming service.
Once the names are resolved, they proceed to update the symbols as in Part 2. Errors are handled in the same
way as in Part 2. The packet exchanged between the client/broker/exchange is the same as before. Note that each
OnlineBroker is exclusively launched for TSE or Nasdaq and is only allowed to access and update its corresponding
symbol/quotes file. Similarly, each exchange is dedicated to TSE or Nasdaq exclusively.
4.2 Grading
The weight of this part in the overall Lab 1 grade is 40%. An interactive session involving a naming server, two
exchanges, two brokers and one client will be used to grade your work. If the semantics of your output conform to
the specifications, you get full credits. Otherwise, similar grading policies as in the previous parts will be used.
A new command local is introduced to the client. The client session may now look like the following:
[user@ug145 part3]% sh ./client.sh Enter command, symbol or x for exit:
> local tse
tse as local.
> EMC
Quote from broker: 4
> RIM
Quote from broker: 1
> local nasdaq
nasdaq as local.
> MSFT
Quote from broker: 28
> RIM
Quote from broker: 1
> x
[user@ug145 part3]%
Similar to the file nasdaq of previous parts, you are provided with two files of nasdaq and tse as the starting
points of your sessions. The example sessions of the exchanges (Nasdaq and TSE) are identical to those in Part
1. Both brokers and exchanges specify the location (nasdaq or tse) at the command line when started. Note
that the provided shell scripts pass down all the required command line parameters down to your Java code. You
need to look into the content of each shell script to learn about these parameters. You should name your main
classes for client/broker/exchange based on what the related shell script expects as the main class. Since each script
passes all the required command line parameters to your Java code, you should not need to change the script. A
new script lookup.sh is provided for you to launch your naming server which should have its main class called
BrokerLookupServer.
You should use a single exchange code but launch it in TSE or Nasdaq role by passing a command line parameter.
Similarly, you will have a single OnlineBroker code stream which will be configured at runtime to be a TSE or
Nasdaq broker through a command line parameter.
As a helpful note, use the provided script files as a guide to organize and write your code.
5 Submission
Only one team member needs to submit the assignment. Include the names and student numbers for both team
members in a README file in the topmost directory, as illustrated below.
6
Your submission should be divided into three parts (organized in three separate directories broker1, broker2
and broker3). Each part should include an appropriate Makefile. You can feel free to use the sample makefiles
that are provided to you, or you can write your own makefiles.
Your submission must be in the form of one compressed archive named Lastname1.Lastname2.tar.gz. The
directory structure of the archive should be as follows:
Lastname1.Lastname2.Lab1/
—README
—+broker1/
——README
——client.sh
——server.sh
——Makefile
——nasdaq
——
—+broker2/
——README
——client.sh
——server.sh
——exchange.sh
——Makefile
——nasdaq
——
—+broker3/
——README
——client.sh
——server.sh
——exchange.sh
——lookup.sh
——Makefile
——nasdaq
——tse
——
For each part, the compressed archive is required to include a README file if and only if your code requires a
custom setup to run, i.e., other than execution through the provided scripts. The provided scripts should be good
enough for the purpose of this lab unless you want to pass extra parameters to your code for some added features.
Each part has to have a Makefile, along with all source files required to compile for that part. When we check
your solutions for each part, we simply enter the corresponding subdirectory, and type make at the command line
prompt to compile your source code. We will then use sh client.sh or similar commands to run the client, the
server or the exchange, with additional command-line options that you may specify in the README.
If you need to provide any additional explanations about your solutions, please do so in the general README file
in the topmost directory, illustrated previously. This README file should include the names and student numbers
for both team members.
Once you have a compressed archive in the .tar.gz format, you may submit your solution by the deadline using the submitece419s command, located under /local/bin on the ug machines:
/local/bin/submitece419s 1 Lastname1.Lastname2.tar.gz
7
