Data Structures Course - Spring 2004 - Programming Ex1



General Description

Recently you have been informed that aunt Bz'ez'enya (a distant relative you have heard nothing about so far) tragically found her death in a daring operation in the war in Iraq. (You are not even sure which side was she on but let's leave that on that). To soften the blow, Bz'ez'enya left you a considerable sum of money "To benefit both your financial future and the cultural world in which we live" (as she put on the will).
Naturally, you've decided to open a book store.

As a proud young computer scientist, you've decided to write your own software to maintain the store's inventory and catalog.
The catalog contains the collection of books generally available from publishers. The inventory is the collection of books you have in stock at the store along with the number of copies available from each book. Books that are in the catalog but not in stock can be ordered in.

During the course you will gradually improve the software support for managing your store (that is if you won't go bankrupt).

In this Exercise you will have to implement the infrastructure of the system,using the basic data structures studied so far. Later on you will add more sophisticated data structures to your application.

Input and Output

Since you want your program to be superb in every aspect, you would also like to have an amazing Graphic User Interface (GUI). Unfortunately, your GUI programming skills are still somewhat limited. In order to be able to write a suitable GUI in the future, you decided that all input to your program and output from your program will be made using a predefined interface.
The interface also defines the possible commands your program might receive. Each command is given as a function in the interface, another program (e.g. GUI or grader) may call your implementation of the functions defined in the interface. The interface is divided into two parts:
  1. OutputManager
    Contains basic output operations your program will need to perform. We will provide an object named PrintManager that implements every function in this interface as a static function. This means that if you want to output a book who's title is "Harry Potter", his author is "J. K. Rollins", and his price is 89, you use the command
    PrintManager.outputCatalogBook( "Harry Potter", "J. K. Rollins", 89 );
    We have implemented the PrintManager so you can use it for testing your program. you can download the PrintManager class from: PrintManager.class and put it in your bookstore directory (the PrintManager is a part of the bookstore package).
  2. CommandManager
    The commands your program might receive. You should provide implementation for this interface. We will check your program by calling the functions from this interface.

How your program receives commands

In order to simulate an interaction with an operator, your program will receive operator commands (through calls to the predefined interface). This means that other programs (e.g. GUI or grader) will call your implementation for the functions defined in the predefined interface. Your program is expected to output using calls to the predefined interface.

Your output file will be processed automatically by other programs which you did not write nor do you control. For example, your accountant software in the story world (or the grader in our own world).
So it is very important that you use the predefined interface for input and output.
Do NOT print anything to standard output or error except through the predefined interface. Failure to do so will result in a failing grade. You should NOT print headers , graphics or other data unless you were explicitly asked to do so (for example in PrintCatalog). Any syntactical problem in output that prevents automatic processing is as major error as any other.

Error handling

The errors you are required to check are logical errors. We have defined a BookstoreException. In the CommandManager interface we stated whenever a method might throw a BookstoreException, deciding in what cases to throw a BookstoreException is part of the exercise. For example, the removeCatalogTitle command will throw a BookstoreException in case it is called with a book title that does not appear in the catalog.
You may also throw exceptions that are always defined in Java, such as NullPointerException. In case an error occurred, (besides throwing appropriate exception,) the command should be skipped.

Basic data structures

In the future, you will learn more sophisticated data structures. This means you will be able, and be asked to, improve the performance of your program. Since you would like to rewrite as little as possible we recommend, using the following interfaces:
In the package dast.util there are interfaces for several basic data structures. You can find a jar file containing the package here. We recommend that you implement the SortedMap interface. For now, a doubly linked list implementation of the SortedMap interface will do. (Please describe the asymptotic efficiency of each operation in the documentation).
Note that implementing SortedMap also means that you have to implement other interfaces besides SortedMap. For example, Iterator (returned by entries()).

Another Interface you might benefit from implementing is a Queue since you will need it for your program in the future. (people taking the reduced course should skip that one.)

NOTE: In any case, you are not allowed to use any of the Java-API's data structures. You MUST implement them by yourselves. You are allowed to use other Java-API classes (e.g. for string manipulation, I/O, etc.).

For an example of how to implement a general data structure, see the VectorCollection class that implements the Collection interface. This is also an example of how to write an iterator (see the Iterator interface). For an example of how to work with comparators, see the CarTaskManager class, the Car class, and the CarComparator class.

The bookstore package and how to run the program

You should write all the classes of your application under a package named bookstore.
Your package should contain a class named MyStoreManager.java that implements the CommandManager interface defined above. Make sure the name of your class is MyStoreManager, otherwise our main won't be able to load it.
You can create your a main class for testing your bookstore inside the bookstore package or where ever you like. If you create it outside the bookstore package remember you should add the full path of the package to your CLASSPATH. In any case, do not submit your main class.

Submission guidelines

You are allowed to submit this exercise in pairs (which means, only one of you would actually submit the exercise).

You must submit this exercise until 28/03/2004, 12:00 noon. This submission date is final, no extensions will be given.

The total grade will be 0.5 times the manual grade plus 0.5 times the automatic grade. (The purpose of the automatic check is to find bugs in your program...)
Detailed instructions on how to submit are here. Read them carefully!!!
When preparing the jar file for submission, follow the these instructions:
  1. Create a new directory named 'ex1'.
  2. Under it create a subdirectory 'bookstore' (if you have additional packages which you created for your program, for example: bookstore/util, create the needed subdirectories as well).
  3. Copy all the '.java' files of your package 'bookstore' into ex1/bookstore (copy all '.java' of your other packages (if there are any) to the needed subdirectory as well).
    Copy your readme file into ex1/
    Check that your readme file matches the requirements specified here. In particular, verify that the first line contains only your login name, and that the file name is indeed 'readme' (and not 'Readme', 'readme.txt', etc.)
  4. cd into ex1. Now 'ls' should show something like: 
           bookstore/      readme
  5. Execute: 
           jar cvf ex1.jar readme bookstore
  6. Now you should have a file 'ex1.jar' that contains all the files you need to submit.
  7. Before you actually submit, you are REQUIRED to test your jar file using the program ~dast/bin/testEx1.csh. You should run this program (by simply typing this string, which is the program name) from the directory where 'ex1.jar' is located. This program opens your jar file, compiles your MyStoreManager, performs few simple tests, and performs 'diff -b' to check your ouput versus ours. If this programs prompts you that everything went ok, you can submit. Otherwise you should fix your problems and re-run it. Don't submit until the program prints that everything went OK.
  8. Submit the printouts of your README file and ALL the java files you wrote for the implementation of your book store to the dast (physical) inbox in Ross -2 (do not submit our interfaces, we are already familiar with them, do not submit javadoc, save your quota and go easy on those trees).


Special Notes

  1. Questions and Comments should be sent to the newsgroup local.course.dast.ta. This newsgroup will hold all the latest and most up-to-date information about ex1 (if you can't see the news group, the new server is nntpserver.cs.huji.ac.il and the news group is local.course.dast.ta).
    You can also use the newsgroup local.course.dast.stud for student communication. The TA's will not answer questions directed to this newsgroup.
  2. Remember that the next homeworks are based on this one. If you build your program in a modular way then it will be easy to change it, replace one data structure with another, etc. So, we recommend that you plan carefully to make your program as modular as possible.
  3. Document your code well, to make it easy to read and understand. This means easy for US to understand.
  4. Note, that programming assignments usually take a lot of time. Furthermore, most of the time is spent on "unexpected debugging". You will probably encounter many bugs, and you should plan your time accordingly.