CIT 590 Assignment 8: Library
Spring 2010, David Matuszek

Purpose of this assignment

To get you started with Java

General idea of the assignment

This assignment is similar to, but not identical with, one that you have done recently in Python. There are a lot of minor changes to transition from Python to Java, and a few to just improve the program design.

You are going to implement software for your local library. The user of the software will be the librarian, who uses your program to issue library cards, check books out to patrons, check books back in, send out overdue notices, and open and close the library.

Library rules:

You must have a library card in order to check out books.
You can have at most 3 books checked out at a time.
Books are due one week (7 days) after being checked out--no renewals.
You will receive an overdue notice (just one) when a book becomes overdue.
- The notice will list all the books you have checked out, and will indicate which ones are overdue.

Details

In a number of methods, we will make a distinction between what the program appears to do (its behavior), and what it actually does (its implementation). For example, when we "issue a library card" to a patron, we don't create some kind of a "library card object" and give it to a Patron object; the implementation will achieve the same result by simply recording the patron's name in a HashMap. The visible behavior is the same: A person who has been "issued a library card" will be able to check out books. Don't let yourself be confused by the differences between the behavior and the implementation.

I don't think you will need any additional classes, but you are likely to need some additional methods, not listed below. Feel free to write more methods (but remember to test them).

Classes and methods

`class Calendar`

We need to deal with the passage of time, so we need to keep track of Java. Python has a perfectly good GregorianCalendar class, but to keep things simple, we will just use an integer (starting from 0) to keep track of how many days have passed. Declare this variable as private int date within the class itself, not within any method or constructor of the class.

We only need a couple of methods:

Calendar(): The constructor. Sets the date to 0. You should create one and only one Calendar object; time is the same for everyone.
int getDate(): Returns (as an integer) the current date.
void advance(): Increment the date (move ahead to the next day).

`class Book`

A book has these attributes (instance variables): its title, its author (only one author per book), and its dueDate. The due date is -1 if the book is not checked out. These should be instance variables.

Book(String title, String author): The constructor. Saves the provided information. When created, this book is not checked out.
String getTitle(): Returns this book's title.
String getAuthor(): Returns this book's author.
int getDueDate(): Returns the date (as an integer) that this book is due.
void checkOut(int date): Sets the due date of this Book to the specified date. It is not this Book's job to remove itself from the Library's collection of available books.
void checkIn(): Sets the due date of this Book to -1. It is not this Book's job to return itself to the Library's collection of available books.
@Override public String toString(): Returns a string of the form title, by author.

`class Patron`

A patron is a "customer" of the library. A patron must have a library card in order to check out books. A patron with a card may have no more than three books at any time.

Patron(String name, Library library): Constructs a patron with the given name, and no books. The patron must also have a reference to the Library object that he/she uses.
String getName(): Returns this patron's name.
void take(Book book): Adds this book to the list of books checked out by this Patron.
void giveBack(Book book): Removes this Book object from the list of books checked out by this Patron. (Since patrons are usually said to "return" books, I wish I could name this method return, but I hope you can see why I can't do that.)
ArrayList<Book> getBooks(): Returns the list of Book objects checked out to this Patron (may be an empty list).
@Override public String toString(): Returns this patron's name. (Yes, this is the same as the getName() method!)

`class OverdueNotice`

Represents an "overdue notice" that contains a list of all the books checked out to this user, along with their due dates, and indicates which ones are overdue.

OverdueNotice(Patron patron, int todaysDate): Constructs an overdue notice for the given Patron. (What it actually does is save the patron in an instance variable, and saves today's date in another instance variable.)
@Override public String toString(): Returns as a String, in a nice, humanly readable format, an overdue notice. The notice should list all the books currently checked out by the patron, along with their due dates, and call attention to which ones are overdue. (This method allows the Patron to easily print out the overdue notice.)

`class Library`

This is the "master" class. It has a number of methods which are called by the "librarian" (the user), not by patrons. The librarian does all the work. Since these methods (other than the constructor) will be typed in by the librarian, all the parameters must be strings or numbers, not objects (how would you type in a Book object?). Furthermore, to reassure the librarian that his/her action has worked, all these methods should result in an informative printout, for example, "Library card issued to Amy Gutmann."

To enable I/O free unit testing, all these methods should call either the local print or println methods described below to do their printing, not the System.out versions.

public Library(): This is the constructor that will be used by the librarian, once, to "create the library. It also sets a private instance variable okToPrint to true.

To construct the library object, ask the user for the name of a file, then read in from the file a list of title :: author lines, create a Book from each line, and save these in an ArrayList<Book>. These Books form the library's collection. Do not assume that there is only one copy of each book.

Of course, when the library is created, none of the books are checked out. There are not yet any patrons, either, but you should define an empty HashMap (whose keys will be the names of patrons and whose values will be the corresponding Patron objects).
public Library(ArrayList<Book> collection): This is a second constructor, used by the test methods. This constructor sets the private instance variable okToPrint to false, so that the unit tests can be "cleaner" and not do any I/O. With this constructor, the user isn't asked for a list of books to read in; the list is supplied as a parameter. (It is okay to call this constructor as often as desired.)
public static void main(String[] args): This creates one Library object and calls its start method.
void start(): In Java, the user cannot call methods directly from the keyboard. This method will read one or two word commands from the user, such as open or search saga, call the corresponding method, and print the results.
void print(String message): If the instance variable okToPrint is true, prints the message using System.out.print(message), otherwise this method returns without doing anything.
void println(String message): If the instance variable allowPrinting okToPrint is true, prints the message using System.out.println(message), otherwise this method returns without doing anything.
ArrayList<OverdueNotice> open(): Starts the day (by advancing the calendar). Then sends overdue notices to all patrons with overdue books (by calling the next method, and printing the results). Sets an instance variable to indicate that the library is now open. Returns the list of notices that it got from calling createOverdueNotices.
ArrayList<OverdueNotice> createOverdueNotices(): Checks each Patron to see whether he/she has books which were due yesterday. For each such patron, creates and returns a list of overdue notices. (The librarian doesn't have to do this as a separate command; it's done whenever the library is opened.)
Patron issueCard(String nameOfPatron): Issues a library card to the person with this name. (What this actually does is, it creates a Patron object, and saves it as the value in a HashMap, with the patron's name as the key. No patron can have more than one library card. The created Patron object is returned as the value of the method.
Patron serve(String nameOfPatron): Begin checking books out to (or in from) the named patron. The purpose of this method is so that the librarian doesn't have to type in the person's name again and again for every book that is to be checked in or checked out. What the method should actually do is look up the patron's name in the HashMap, and save the returned Patron object in an instance variable of this Library. In addition, the method should return the Patron object.
ArrayList<Book> checkIn(int... bookNumbers): The listed books are being returned by the current Patron (there must be one!), so return them to the collection and remove them from the list of books currently checked out to the patron. The bookNumbers are taken from the list printed by the serve command. Checking in some books should not alter the printed book numbers of any other books. Checking in a Book will involve both telling the Book that it is checked in and returning the Book to this Library's collection of available Books. Returns a list of the books just checked in.
ArrayList<Book> search(String part): Prints out, and saves in an instance variable, an ArrayList<Book> of books whose title or author (or both) contains this string. For example, the string "tact" might return, among other things, the book Contact, by Carl Sagan. The search should be case-insensitive; that is, "saga" would also return this book. Only books which are currently available (not checked out) will be returned. In addition, to keep from returning too many books, require that the search string be at least 4 characters long. If multiple copies of a book are found (for instance, three copies of Contact), only one copy should be printed. Returns a list of the books just found.
ArrayList<Book> checkOut(int... bookNumbers): Either checks out the book to the Patron currently being served (there must be one!), or tells why the operation is not permitted. The bookNumbers are one or more of the books returned by the most recent call to the search method. Checking out a Book will involve both telling the Book that it is checked out and removing the Book from this Library's collection of available Books. Returns a list of the books just checked out.
void close(): Shut down operations and go home for the night. None of the other operations (except quit) can be used when the library is closed.
void quit(): End the program. The mayor, citing a budget crisis, has stopped all funding for the library. Can happen at any time.

Checking books in and out is slightly complex, so here is what the librarian needs to know:

To check books in:
     1. If you have not already done so, serve the patron. This will print a numbered list of books checked out to that patron.
     2. checkIn the books by the numbers given above.
To check books out:
     1. If you have not already done so, serve the patron. You can ignore the list of books that this will print out.
     2. search for a book wanted by the patron.
     3. checkOut zero or more books by the numbers returned from the search command.
     4. If more books are desired, you can do another search.

Note on new syntax

Two of the methods above, checkOut and checkIn, have an elllipsis ("...") in front of the parameter. That elllipsis is new syntax--it means that, when you call the method, you can give as many book numbers as you please; you don't have to give just one. Inside the method, the parameter bookNumbers is an array of all the numbers (zero or more) that you gave it.

Getting started

Use Eclipse to create the Library project, the library package, and all the classes. Then add to each class a "stub" for each method. A stub is a method that does nothing or, if it must return something, returns a seriously inappropriate value (null for objects).

Testing

General rules:

All methods (including constructors) should be tested, unless their purpose is to do input or output.
Testing methods should not result in any input requests or output.

I will provide unit tests as soon as I can (almost certainly this weekend).

Hints

Java style requires that each class be put in a separate file. Eclipse does this automatically when you create a new class. Tests should normally be kept separate from the program being tested.

Instance variables are variables that belong to an object, and instance methods are methods that are defined for an object. Instance variables and methods may be prefixed with this. , when used by the object itself, but usually you only need to do this to distinguish an instance variable from a local variable or parameter with the same name.

When an object uses the methods of another object, those methods must be prefixed by a variable that refers to the object; for example, book.getTitle().

Grading:

You and your partner should decide who is to turn in the program, and you should submit one program for the two of you. Both of you will receive the same grade on the program.

Due date:

Midnight Thursday, March 25. Zip or jar all files and submit via Blackboard--do not turn in a .rar file. The author or authors of each class should be prominently displayed in a comment at the top of the class.