4005-730-01 Distributed Systems
Programming Project 1

Overview
Geographic Package System
Software Requirements
Submission Requirements
Grading Criteria
Late Projects
Plagiarism
Resubmission

Write a distributed system in Java for a package tracking system called Geographic Package Service (GPS). The GPS system will include distributed objects and client programs, residing in multiple processes, running on different host computers, and communicating with each other using Java remote method invocation (RMI).

The GPS Company provides customers with a package delivery service. GPS delivers a package to a destination specified by geographic coordinates (longitude and latitude, or X and Y), not postal addresses. GPS uses an experimental version of Star Trek's transporter technology to beam a package to its destination. Because the transporter has a limited range (it's still experimental, after all), GPS cannot necessarily beam a package directly to its final destination. Instead, the service works like this:

• GPS has a number of offices in different cities at certain (X,Y) locations.

• Each GPS office is able to beam a package to any of its neighboring GPS offices. The neighbors are defined as follows:

  • If there is one GPS office in the system, then that GPS office has no neighbors.

  • If there are two GPS offices in the system, then each GPS office has one neighbor, which is the other GPS office.

  • If there are three GPS offices in the system, then each GPS office has two neighbors, which are the other two GPS offices.

  • If there are four GPS offices in the system, then each GPS office has three neighbors, which are the other three GPS offices.

  • If there are five or more GPS offices in the system, then each GPS office has three neighbors, which are the other three GPS offices closest to itself.

  • Closeness is measured using the usual Euclidean distance: The distance between office A at location (X1,Y1) and office B at location (X2,Y2) is ((X1 − X2)² + (Y1 − Y2)²)^1/2.

  • New GPS offices can open and existing GPS offices can close at any time. If a GPS office opens or closes, the other GPS offices' neighbor sets might change.

• A customer goes to a GPS office with a package to be sent to a certain (X,Y) destination. The GPS office assigns a tracking number to the package. The package then commences its journey through the GPS system.

• When a package arrives at a GPS office (including the originating office):

  • The package undergoes an examination to make sure it is intact. This examination takes 3 seconds.

  • If the package's final destination is closer to this GPS office than to any of this GPS office's neighbors, the package is instantaneously beamed to its final destination.

  • Otherwise, the package is instantaneously beamed to one of this GPS office's neighbors, namely the neighbor that is closest to the package's final destination.

• For tracking purposes, each GPS office informs the customer when the package arrives and when the package departs.

• Each GPS office also informs GPS corporate headquarters when any package arrives and when any package departs.

The GPS distributed system consists of the following components:

• A distributed object to represent one GPS office.
• A client program to represent a customer sending a package.
• A client program to represent GPS corporate headquarters.
• The Registry Server from the Computer Science Course Library.

Any number of GPS office objects and any number of clients may be running simultaneously. Only one Registry Server is running. It is assumed that the Registry Server does not fail.

GPS Office Object

1. The system must have a Java RMI remote object class for a GPS office, of which any number of instances may be running.

2. An instance of the GPS office object must be run by typing this command line:

   java Start GPSOffice <host> <port> <name> <X> <Y>
   

   • <host> is the name of the host computer where the Registry Server is running.
   • <port> is the port number to which the Registry Server is listening.
   • <name> is the name of the city where the GPS office is located.
   • <X> is the GPS office's X coordinate (type double).
   • <Y> is the GPS office's Y coordinate (type double).

   Note: This means that the GPS office object's class must be named GPSOffice, this class must not be in a package, and this class must define the appropriate constructor for the Start program.

   Note: The Registry Server is an instance of class edu.rit.ds.registry.RegistryServer.

3. The GPS office object's constructor must throw an exception if there are any of the following problems with the command line arguments. The exception's detail message must be a meaningful explanation of the problem.
   • Any required argument is missing.
   • There are extra arguments.
   • The port argument cannot be parsed as an integer.
   • The X or Y argument cannot be parsed as a double.
   • There is no Registry Server running at the given host and port.
   • Another GPS office with the same city name is already in existence.
   • Any other error condition is encountered while starting up the GPS office object.

4. The GPS office object must behave as described under Geographic Package System above.

5. When a package first enters the system, the originating GPS office must assign the package's tracking number; the tracking number must be the value returned by System.currentTimeMillis().

6. The GPS office object must not print anything.

7. The GPS office object must continue running until killed externally.

   Customer Client Program

8. The system must have a client program for a customer sending a package, of which any number of instances may be running.

9. An instance of the client program must be run by typing this command line:

   java Customer <host> <port> <name> <X> <Y>
   

   • <host> is the name of the host computer where the Registry Server is running.
   • <port> is the port number to which the Registry Server is listening.
   • <name> is the name of the city where the originating GPS office is located.
   • <X> is the package's destination's X coordinate (type double).
   • <Y> is the package's destination's Y coordinate (type double).

   Note: This means that the client program's class must be named Customer, and this class must not be in a package.

   Note: The Customer program is a client program, not a distributed object.

   Note: The Registry Server is an instance of class edu.rit.ds.registry.RegistryServer.

10. The client program must print an error message on the console and must terminate if there are any of the following problems with the command line arguments. The error message must be a meaningful explanation of the problem. The error message may include an exception stack trace.
    • Any required argument is missing.
    • There are extra arguments.
    • The port argument cannot be parsed as an integer.
    • The X or Y argument cannot be parsed as a double.
    • There is no Registry Server running at the given host and port.
    • There is no GPS office object for the given city name.

11. Whenever the customer's package arrives at a GPS office (including the originating office), the client program must print the following message on the console:

    Package number <tracknum> arrived at <name> office
    

    where <tracknum> is replaced by the package's tracking number and <name> is replaced by the city name of the GPS office at which the package arrived.

12. Whenever the customer's package departs from a GPS office (including the originating office) en route to another GPS office and the GPS office encounters no errors while forwarding the package, the client program must print the following message on the console:

    Package number <tracknum> departed from <name> office
    

    where <tracknum> is replaced by the package's tracking number and <name> is replaced by the city name of the GPS office from which the package departed.

13. Whenever the customer's package departs from a GPS office (including the originating office) en route to another GPS office and the GPS office encounters an error while forwarding the package, the client program must print the following message on the console and must terminate:

    Package number <tracknum> lost by <name> office
    

    where <tracknum> is replaced by the package's tracking number and <name> is replaced by the city name of the GPS office from which the package departed.

14. When the customer's package is delivered from a GPS office (including the originating office) to the package's final destination, the client program must print the following message on the console and must terminate:

    Package number <tracknum> delivered from <name> office to (<X>,<Y>)
    

    where <tracknum> is replaced by the package's tracking number, <name> is replaced by the city name of the GPS office that delivered the package, <X> is replaced by the X coordinate of the package's destination, and <Y> is replaced by the Y coordinate of the package's destination.

15. If the client program encounters an error condition not mentioned above, the client program must print an error message on the console and must terminate. The error message must be a meaningful explanation of the problem. The error message may include an exception stack trace.

16. The client program must not print anything other than specified above.

    Headquarters Client Program

17. The system must have a client program for GPS corporate headquarters, of which any number of instances may be running.

18. An instance of the client program must be run by typing this command line:

    java Headquarters <host> <port>
    

    • <host> is the name of the host computer where the Registry Server is running.
    • <port> is the port number to which the Registry Server is listening.

    Note: This means that the client program's class must be named Headquarters, and this class must not be in a package.

    Note: The Headquarters program is a client program, not a distributed object.

    Note: The Registry Server is an instance of class edu.rit.ds.registry.RegistryServer.

19. The client program must print an error message on the console and must terminate if there are any of the following problems with the command line arguments. The error message must be a meaningful explanation of the problem. The error message may include an exception stack trace.
    • Any required argument is missing.
    • There are extra arguments.
    • The port argument cannot be parsed as an integer.
    • There is no Registry Server running at the given host and port.

20. Whenever a package arrives at a GPS office (including the originating office), the client program must print the following message on the console:

    Package number <tracknum> arrived at <name> office
    

    where <tracknum> is replaced by the package's tracking number and <name> is replaced by the city name of the GPS office at which the package arrived.

21. Whenever a package departs from a GPS office (including the originating office) en route to another GPS office and the GPS office encounters no errors while forwarding the package, the client program must print the following message on the console:

    Package number <tracknum> departed from <name> office
    

    where <tracknum> is replaced by the package's tracking number and <name> is replaced by the city name of the GPS office from which the package departed.

22. Whenever a package departs from a GPS office (including the originating office) en route to another GPS office and the GPS office encounters an error while forwarding the package, the client program must print the following message on the console:

    Package number <tracknum> lost by <name> office
    

    where <tracknum> is replaced by the package's tracking number and <name> is replaced by the city name of the GPS office from which the package departed.

23. Whenever a package is delivered from a GPS office (including the originating office) to the package's final destination, the client program must print the following message on the console:

    Package number <tracknum> delivered from <name> office to (<X>,<Y>)
    

    where <tracknum> is replaced by the package's tracking number, <name> is replaced by the city name of the GPS office that delivered the package, <X> is replaced by the X coordinate of the package's destination, and <Y> is replaced by the Y coordinate of the package's destination.

24. If the client program encounters an error condition not mentioned above, the client program must print an error message on the console and must terminate. The error message must be a meaningful explanation of the problem. The error message may include an exception stack trace.

25. The client program must not print anything other than specified above.

26. The client program must continue running until killed externally.

    General Requirements

27. The distributed objects and client programs must operate in the manner described under Geographic Package System above.

    Design Restrictions

28. The GPS office objects must be the only objects bound into the Registry Server.

29. A GPS office object method called by a client program must not call methods on any other GPS office object.

    Hint: Consider utilizing a thread pool from package java.util.concurrent.

30. The customer client program must call methods only on the GPS office object specified on the command line. The customer client program must not call methods on any other GPS office object.

Your project submission will consist of a Java archive (JAR) file containing the Java source files for your client program.

• Each Java source file name must end in ".java".

• Each class or interface must include a Javadoc comment describing the overall class or interface.

• Each method within each class or interface must include a Javadoc comment describing the overall method, the arguments if any, the return value if any, and the exceptions thrown if any.

See my Java source files which we studied in class for the style of Javadoc comments I'm looking for.

Put all the source files into a JAR file named "<username>.jar", replacing <username> with the user name from your Computer Science Department account. The command is:

jar cvf <username>.jar *.java

If your program uses classes or interfaces from the Computer Science Course Library without changes, then you do not need to include these classes' or interfaces' source files in your JAR file. If your program uses classes or interfaces from the Computer Science Course Library with changes, then you do need to include these classes' or interfaces' source files in your JAR file.

Send your JAR file to me by email at ark­@­cs.rit.edu. Include your full name and your computer account name in the email message, and include the JAR file as an attachment.

When I get your email message, I will extract the contents of your JAR file into a directory. However, I will not replace any of the source files in the Computer Science Course Library with your source files; your project must compile and run with your files in their own separate directory. (You can do this project without needing to replace any source files in the Computer Science Course Library.) I will set my Java class path to include the directory where I extracted your files and the directory where the Computer Science Course Library is installed. I will compile all the source files using the JDK 1.6.0 compiler. I will then send you a reply message acknowledging I received your project and stating whether I was able to compile all the source files. If you have not received a reply within one business day (i.e., not counting weekends), please contact me. Your project is not successfully submitted until I have sent you an acknowledgment stating I was able to compile all the source files.

The submission deadline is Tuesday, April 2, 2013 at 11:59pm. The date/time when your email message arrives in my inbox (not when you sent the message) will determine whether your project meets the deadline.

You may submit your project multiple times before the deadline. I will keep and grade only your most recent submission that arrived before the deadline. There is no penalty for multiple submissions.

If you submit your project before the deadline, but I do not accept it (e.g. I can't compile all the source files), and you cannot or do not submit your project again before the deadline, the project will be late (see Late Submissions below). I strongly advise you to submit the project several days before the deadline, so there will be time to deal with any problems that may arise in the submission process.

Your project will be graded as follows:

• (5 points) GPS office object remote interface design
• (5 points) GPS office object implementation design
• (5 points) Customer program implementation design
• (5 points) Headquarters program implementation design
• (20 points) Test cases
• (40 points) Total

I will evaluate the design of your interfaces and implementations as documented in the Javadoc and as implemented in the source code. Your project should:

• Be designed using object oriented design principles.
• Make use of reusable software components where appropriate.
• Be documented using proper Javadoc style as described above.
• Follow the distributed system design patterns studied in class.

Each portion of the design will be graded as follows:

• 5 = Design good, Javadoc good
• 4 = Design good, Javadoc unacceptable
• 3 = Design needs minor improvements
• 2 = Design needs major improvements
• 0 = Unacceptable

I will run test cases on your project to determine whether all the Software Requirements were correctly implemented. The test cases will be graded as follows:

• 20 = Project runs and all requirements correctly implemented
• 10 = Project runs but some requirements not correctly implemented
• 0 = Project does not run

If any of the objects or programs cannot be run using the command lines specified in the above Software Requirements, you will receive 0 points for the test cases portion of your grade, and I will not test your project further.

If there is any deviation from the requirements, no matter how small, you will receive 10 points for the test cases portion of your grade, and I will not test your project further. This includes errors in the output formatting, such as misspellings, incorrect number of spaces, incorrect capitalization, incorrect punctuation, missing characters, or extraneous characters. The requirements state exactly what the output is supposed to be, and there is no excuse for outputting anything different. If any requirement is unclear, please ask for clarification.

I may run the Registry Server, distributed objects, and client programs on the same computer or on separate computers.

When I run the Registry Server, the Java classpath will point only to the directory where the Computer Science Course Library is installed. There is no need for the Registry Server classpath to point to the directory with your compiled class files because you are not changing the implementation of the Registry Server.

When I run your distributed objects and client programs, the Java classpath will point first to the directory with your compiled class files, followed by the directory where the Computer Science Course Library is installed.

After grading your project I will put your grade and any comments I have in your encrypted grade file. For further information, see the Course Grading and Policies and the Encrypted Grades.

If I have not received a successful submission of your project by the deadline, your project will be late and will receive a grade of zero. You may request an extension for the project. There is no penalty for an extension. See the Course Policies for my policy on extensions.

Programming Project 1 must be entirely your own individual work. Programming Project 1 is not to be done as a team effort. I will not tolerate plagiarism. If in my judgment the project is not entirely your own work, you will automatically receive, as a minimum, a grade of zero for the assignment. See the Course Policies for my policy on plagiarism.

If you so choose, you may submit a revised version of your project after you have received the grade for the original version. You are allowed to make one and only one resubmission of the project. However, if the original project was not successfully submitted by the (possibly extended) deadline or was not entirely your own work (i.e., plagiarized), you are not allowed to submit a revised version. Submit the revised version via email in the same way as the original version. I will accept a resubmission up until 11:59pm Saturday 20-Apr-2013. I will grade the revised version using the same criteria as the original version, then I will subtract 4 points as a resubmission penalty. The revised grade will replace the original grade, even if the revised grade is less than the original grade.

Distributed Systems 4005-730-01 Spring Quarter 2013

Course Page

Alan Kaminsky • Department of Computer Science • Rochester Institute of Technology • 4486 + 2220 = 6706

Home Page

Copyright © 2013 Alan Kaminsky. All rights reserved. Last updated 13-Apr-2013. Please send comments to ark­@­cs.rit.edu.