Overview
In this project you will implement a server for the Purdue Safe Walk Program. The server you are going to write will handle requests and commands sent from the user.
Safe Walk is a campus safety system (currently done manually) that allows people on campus to request that someone walk with them from one location to another on campus. For more details, refer to
this document
.
Definitions
Here are some definitions and terms that will be used throughout this project.
Locations
A location is a building in Purdue campus. A location is identified by a unique acronym. First, for simplicity, the following
locations
will be defined in the system:
CL50
: Class of 1950 Lecture Hall
EE
: Electrical Engineering Building
LWSN
: Lawson Computer Science Building
PMU
: Purdue Memorial Union
PUSH
: Purdue University Student Health Center
*
: Any one of the location above
You may think of
*
as a wildcard that matches with
any
of the first five locations.
As you will see later, a user message will contain two locations,
FROM
and
TO
. Locations not on the list above will be considered invalid.
User
A user is anyone who sends content to the server.
Requester
A requester is a user who asks for help (instead of sending commands). Again, as you will find later, not all users are requesters.
Prerequisites
Knowledge of file I/O operations.
Knowledge of
Java List API
.
Objectives
Understand and use the
Java Socket API
to implement an
iterative
server.
More specifically,
java.net.ServerSocket
for a socket-based server program.
Understand the similarities between files and sockets.
Learn to implement a basic, text-based server-client protocol.
Learn to write exhaustive JUnit tests.
Learn to use simple network utilities
telnet
and netcat (
nc
).
Specifications
Now you are going to write your own server program.
Command-Line Arguments
Name your program
SafeWalkServer
. To run it, use the command
java SafeWalkServer
port
where the
port
argument should be an integer between
1025
and
65535
inclusive. If the
port
argument is given but invalid,
print
an error message (any meaningful message) and exit gracefully. If the
port
argument is not provided, your program should use a port that is automatically allocated, in which case you must print this port number to stdout before the server starts
accept
ing requests. For example,
Port not specified. Using free port 8888.
where
8888
is the port allocated automatically. Note that 8888 is just an example.
If the port is already used (the constructor of ServerSocket will throw an exception). Print an error message and exit gracefully.
Class Constructors
Your
SafeWalkServer
should have two constructors corresponding to the situations where port may or may not be given.
Finish these two methods:
/**
* Construct the server, and create a server socket,
* bound to the specified port.
*
* @throws IOException IO error when opening the socket.
*/
public
SafeWalkServer
(
int
port
)
th.
OverviewIn this project you will implement a server for the Purdue.docx
1. Overview
In this project you will implement a server for the Purdue Safe
Walk Program. The server you are going to write will handle
requests and commands sent from the user.
Safe Walk is a campus safety system (currently done manually)
that allows people on campus to request that someone walk with
them from one location to another on campus. For more details,
refer to
this document
.
Definitions
Here are some definitions and terms that will be used
throughout this project.
Locations
A location is a building in Purdue campus. A location is
identified by a unique acronym. First, for simplicity, the
following
locations
will be defined in the system:
CL50
: Class of 1950 Lecture Hall
EE
: Electrical Engineering Building
LWSN
: Lawson Computer Science Building
PMU
: Purdue Memorial Union
PUSH
: Purdue University Student Health Center
*
: Any one of the location above
You may think of
*
as a wildcard that matches with
any
2. of the first five locations.
As you will see later, a user message will contain two
locations,
FROM
and
TO
. Locations not on the list above will be considered invalid.
User
A user is anyone who sends content to the server.
Requester
A requester is a user who asks for help (instead of sending
commands). Again, as you will find later, not all users are
requesters.
Prerequisites
Knowledge of file I/O operations.
Knowledge of
Java List API
.
Objectives
Understand and use the
Java Socket API
to implement an
iterative
server.
More specifically,
java.net.ServerSocket
for a socket-based server program.
Understand the similarities between files and sockets.
Learn to implement a basic, text-based server-client protocol.
Learn to write exhaustive JUnit tests.
Learn to use simple network utilities
telnet
and netcat (
nc
).
Specifications
3. Now you are going to write your own server program.
Command-Line Arguments
Name your program
SafeWalkServer
. To run it, use the command
java SafeWalkServer
port
where the
port
argument should be an integer between
1025
and
65535
inclusive. If the
port
argument is given but invalid,
print
an error message (any meaningful message) and exit gracefully.
If the
port
argument is not provided, your program should use a port that
is automatically allocated, in which case you must print this
port number to stdout before the server starts
accept
ing requests. For example,
Port not specified. Using free port 8888.
where
8888
is the port allocated automatically. Note that 8888 is just an
example.
If the port is already used (the constructor of ServerSocket will
throw an exception). Print an error message and exit gracefully.
Class Constructors
Your
SafeWalkServer
should have two constructors corresponding to the situations
4. where port may or may not be given.
Finish these two methods:
/**
* Construct the server, and create a server socket,
* bound to the specified port.
*
* @throws IOException IO error when opening the socket.
*/
public
SafeWalkServer
(
int
port
)
throws
IOException
{
//TODO: finish the
method
}
/**
* Construct the server, and create a server socket,
5. * bound to a port that is automatically allocated.
*
* @throws IOException IO error when opening the socket.
*/
public
SafeWalkServer
(
)
throws
IOException
{
//TODO: finish the method
}
Note that the constructors may throw exceptions if any problem
occurs during the execution of the constructor. If the object is
successfully instantiated without exceptions then the server
object is ready to run.
To enable the socket to be reclaimed by the operating system
when the program exits, be sure to set the address to reusable by
calling
setReuseAddress(true)
. For more details, refer to
setReuseAddress
.
Required Methods
Your
SafeWalkServer
6. class must extend
ServerSocket
class and implement the
Runnable
interface. Thus, you must provide a
run
method. You must also provide a method
isPortValid
. The following javadoc comments describe their functionality.
/**
* Start a loop to accept incoming connections.
*/
public
void
run
(
)
{
//TODO: finish this method
}
/**
* Return true if the port entered by the user is valid. Else
return false.
* Return false if you get a NumberFormatException while
parsing the parameter port
7. * Call this method from main() before creating SafeWalkServer
object
* Note that you do not have to check for validity of
automatically assigned port
*/
public
static
boolean
isPortValid
(
String
port
)
{
//TODO: finish this method
}
Note that your server should not start
accept
ing incoming requests before
run()
is called.
To make the server run forever, your
run()
method
may
look something like:
while
8. (
/* condition */
)
{
Socket
client
=
accept
(
)
;
// i.e., do something with client
}
Note that
accept()
blocks the execution of the server until there is an incoming
connection.
Basic Protocol
It is very difficult for two people to communicate if one does
not understand the other's language. Similarly, a server cannot
talk to clients unless they conform to the same protocol. The
protocol that your server uses will be simple text messages.
Client Requests
There are two types of messages that your server needs to
handle:
request messages
and
commands
.
The
request message
is simple text in CSV (comma-separated value) form, with
9. three fields:
NAME
,
FROM
,
TO
where
NAME
is the human-friendly name of the user. You can assume it does
not contain any commas.
FROM
is the location the user wants to move from (
FROM
cannot be
*
).
TO
is the destination of the user's movement (
TO
cannot be the same as
FROM
).
For example, a message
Tom Riddle,LWSN,PUSH
means the person named
Tom Riddle
wants to move from
LWSN
to
PUSH
, while the message
Harry Potter,LWSN,*
means that
Harry Potter
wants to move from
LWSN
10. to
*
location (perhaps to help someone as a volunteer).
There are three
commands
that your server needs to handle. Note that they all start with a
colon (
:
).
:RESET
For each waiting request message, respond with
ERROR: connection reset
and close its socket, before discarding the request.
For the client that originated the command, respond with
RESPONSE: success
and close its socket.
:SHUTDOWN
Gracefully terminate the server (i.e., do what
:RESET
does, close the socket and whatever streams your server uses,
and exit the run loop).
:PENDING_REQUESTS,
TASK
,
FROM
,
TO
TASK
refers to the information that the user is seeking. Valid values
for
TASK
are
#
and
*
.
11. Valid values for
FROM
and
TO
are one of the locations listed above.
Refer to the following table to know the action that needs to
performed for each combination of
TASK
,
FROM
and
TO
. Close the client socket after the write operation. While writing
unpaired request messages, use the 3-tuple form (see example
below)
If a command from the client starts with a colon (
:
) but does not conform to the above specifications then respond
to the client with
ERROR: invalid command
and close its socket.
TASK
FROM
TO
Write to the client socket (Action)
#
*
*
total number of pending requests
#
Any valid location other than
*
*
total number of pending requests starting at
FROM
#
12. *
Any valid location other than
*
total number of pending requests destined to
TO
*
*
*
list all the pending requests
Example commands and their corresponding response messages
are as shown below. Note that these are examples, you should
not hard code values in your program.
You should stick to the format of the response messages shown
below.
:PENDING_REQUESTS,#,LWSN,* // command
RESPONSE: # of pending requests from LWSN = 1 // response
:PENDING_REQUESTS,#,*,PUSH // command
RESPONSE: # of pending requests to PUSH = 2 // response
:PENDING_REQUESTS,#,*,* // command
RESPONSE: # of pending requests = 2 // response
:PENDING_REQUESTS,*,*,* // command
[[Alicia, PMU, PUSH], [Riya, LWSN, EE]] // response
Request/Command Handling
13. Whenever
accept()
returns a
Socket
object, your server has received a new request/command to
handle. Your server should handle a request/command by doing
the following steps:
validity check
,
handle request/command
,
clean up
.
Validity Check
Before performing a request/command, your server should first
check if it is valid. The rules are as follows:
If the text is a command (i.e., starting with
:
), make sure it is in the list of defined commands.
If the text represents a request,
make sure it contains all three tokens (i.e.,
NAME
,
FROM
,
TO
), separated by commas; and that
FROM
and
TO
are known locations;
FROM
cannot be
*
;
TO
14. must be different from
FROM
.
If the request is invalid, respond with
ERROR: invalid request
to the client and close its socket. If the command is invalid,
respond with
ERROR: invalid command
to the client and close its socket.
Handle Request/Command
If the message is a valid command, perform it as specified in
the list of commands.
If the message is a valid request, try to find a
match
for it:
Try to find a pair for the client:
The
FROM
location of paired clients must be the same;
The
TO
location of paired clients must be the same,
or
,
one and only one
can have its
TO
be
*
.
If there is no suitable pair for the requester, put it on hold:
You will need a
list
structure to store outstanding user requests in which to search
for matches.
Do not
15. close
the client socket when storing them because you will need the
connection later.
For this project, you can assume the client will not close the
socket by itself.
If a matched pair is found, move the on-hold client out of the
list, respond to each of the pair their match's request message
prefixed with
RESPONSE:
, and close their sockets.
If a user (e.g., C) can form pairs with more than one user (e.g.,
A and B), then pair it with the oldest on-hand user (e.g., A, if A
submitted its request first). That is, requests are handled in
first-come, first-served order, sometimes also called First-In
First-Out (FIFO).
For example, given
Tom Riddle,LWSN,PUSH
Vegeta,LWSN,EE
Harry Potter,LWSN,*
Andy,CL50,*
Bella,CL50,*
Cyndi,EE,*
Woody,CL50,PMU
Goku,LWSN,EE
Edward,CL50,PUSH
John Doe,PUSH,PMU
16. :PENDING_REQUESTS,*,*,*
the server will do the following:
Tom Riddle is put on hold (added to the list)
Vegeta gets put on hold
Harry Potter is matched with Tom Riddle from
LWSN
to
PUSH
Harry Potter receives
RESPONSE: Tom Riddle,LWSN,PUSH
Tom Riddle receives
RESPONSE: Harry Potter,LWSN,*
Tom Riddle is removed from the list
Andy is put on hold
Bella is put on hold. She cannot be matched with Andy because
they are both going to * (they are volunteers)
Cyndi is put on hold
Woody is matched with Andy from CL50 to PMU
Woody receives
RESPONSE: Andy,CL50,*
Andy receives
RESPONSE: Woody,CL50,PMU
Andy is removed from the list
Goku is matched with Vegeta from LWSN to EE
Vegeta receives
RESPONSE: Goku,LWSN,EE
Goku receives
RESPONSE: Vegeta,LWSN,EE
Vegeta is removed from the list
Edward is matched with Bella (sparkle, sparkle!) from CL50 to
PUSH
John Doe is put on hold
Cyndi is still in the queue, waiting on a user to advertise EE to
anywhere except *
The client who sends
:PENDING_REQUESTS,*,*,*
17. will get
[[Cyndi, EE, *], [John Doe, PUSH, PMU]]
If the server then receives command
:RESET
then
Cyndi
and
John Doe
will get the response
ERROR: connection reset
and have their connections closed.
Use the
readLine
method of
BufferedReader
when reading from input streams, and the
println
method of
PrintWriter
when writing to output streams. Refer to textbook or lecture
slides from week 10 (External Communication) for more details.
Clean Up
After a client has been served (paired with another client, or
connection reset), close its streams and socket gracefully so that
Java garbage collector knows to reclaim the resources.
Self-Testing
For testing the server you can either write JUnit tests or use
networking tools. We strongly suggest that you write JUnit tests
as it can automate the testing process.
Writing Junit Tests
Download
Client.java
. Use this class to start a client from your test method.
Do not make any modifications to the
Client
class.
18. If you are clueless at this point then refer to
Official JUnit
website
Lecture handout
on JUnit. You can download the corresponding programs from
Piazza
Client.java
import
java.io.BufferedReader
;
import
java.io.IOException
;
import
java.io.InputStreamReader
;
import
java.io.PrintWriter
;
import
java.net.Socket
;
import
java.net.SocketTimeoutException
;
19. /**
* Client class for SafeWalkServer
*/
public
class
Client
implements
Runnable
{
private
final
String
host
;
private
final
int
port
;
private
final
31. OS
X, you will have access to two simple UNIX networking tools
that may help you in the initial testing, and are described below.
One is
telnet
. To use
telnet
to send messages to your server, issue the following command
in your terminal:
$ telnet HOST_NAME PORT_NUMBER
where
HOST_NAME
and
PORT_NUMBER
are the host and port on which your server program is running.
Here, you can use
127.0.0.1
or
localhost
as the host name if you wish to connect to a port on the local
machine.
If the connection is established, you can send text by typing it.
The other is
netcat
, which prints the content in its
stdin
to a remote socket, and prints the response to
stdout
. An example command may be
$ nc data.cs.purdue.edu 14180 < client_msg.txt
which assumes your server runs on
data.cs.purdue.edu:14180
and the request message is stored in
client_msg.txt
.
Windows
32. If you are developing on a Windows computer, you may or may
not have access to the
telnet
command by default. You can test this by opening the
command prompt and trying to run it. If you don't have access,
an alternative is to use
ncat
, an implementation of
netcat
for Windows. Download from
here
. Use it with the form
$ ncat
and then type your request or command and hit enter.
Submission
Because this project is for teams of two, be sure to indicate in
the comments of your code the names, login ids and lab sections
of both team members (or just your name, if you worked
alone).
Make sure this comment is at the top of your file (just above the
class definition)
. Also remember to
REMOVE ANY PACKAGE
.
/**
* Project 5
* @author teamMemberOne, login id, labsec
* @author teamMemberTwo, login id, labsec (can be omitted
if working alone)
*/
MANDATORY Intermediate Deadline (April 15, 11:59 pm)
33. :
What you MUST submit?: SafeWalkServer must implement the
isPortValid()
method and the Shutdown and Reset command handling. You
may implement the other features as well, but we will not
consider them while grading the intermediate submission.
Submit
SafeWalkServer.java
for grading using the turn-in command
$ turnin -v -c cs180 -p project5 SafeWalkServer.java
Final Deadline (April 25, 11:59 pm)
:
What you MUST submit?: SafeWalkServer must implement all
the features described in the handout.
Submit
SafeWalkServer.java
for grading using the turn-in command
$ turnin -v -c cs180 -p project5Final SafeWalkServer.java
NOTE:
The intermediate submission
is MANDATORY
. If your intermediate submission correctly implements all the
features asked for the intermediate submission then you will get
30 points. You will get full points (100) for this project only if
your intermediate and final submissions are completely correct.
If for example you don't make the intermediate submission and
implement the full project for the last deadline, the maximum
total score you can get is 70. The
complete
program has to work for the final submission.
For the intermediate submission the implementation of Reset
and Shutdown requires you to understand the request part of
this project. For example, if Alice sends a request to the server,
the server has to handle it but doesn't have to find a match, and
then if Bob sends a
:RESET
34. command, then both Alice and Bob
have to
receive proper response messages.
Suggestion: The invalid commands and requests won't be tested
during the intermediate grading, therefore a
GOOD WAY
of taking advantage of that
MAY
be to consider every messages which are not the Reset or
Shutdown commands as a valid request.
The commands which are not required for the intermediate
submission WON'T be tested while grading your intermediate
submission. Therefore you can freely forget or implement them:
it will not impact your intermediate grade.
Grading Rubric
The grading rubric is as follows:
30 points: Intermediate deadline
10 points: Server can instantiate given valid ports and can have
the
OS
assign a free port to use
5 points:
isPortValid()
10 points: Correct implementation of RESET
5 points: Correct implementation of SHUTDOWN
70 points: Final deadline
50 points: Server can accept valid request messages, find
matches, or queue them when no pair is found, and give correct
match responses
20 points: Correct implementation of pending requests
command