Description
1. Introduction In this assignment you will add file I/O to the email client project from last time. This will allow the program to save its state (meaning address book, inbox, and outbox) to three disk files, and if it is shut down and restarted later, it can load it state from the disk files.
This assignment does not describe how to get your email client to interact with a real mail server. Having you do that is sort of beyond the scope of this course (you’d be capable of doing it, but it’s not a topic we need to cover). However, what I’ll do is try to get that running and then just send you the code that you can plug right into your program to get it working.
2. Due Date This project is due by midnight at the end of the day on Friday, May 1, 2015, but you may submit it by midnight at the end of the day on Sunday, May 3, 2015 without a penalty. A penalty of 20% per day will be deducted from your grade starting at 12:00:01am on Monday May 4. See this link for additional information.
3. Value This program is worth a maximum of 20 points. See the grading rubric at the end for a breakdown of the values of different parts of this project.
4. Objectives This assignment will give you experience using file I/O and handing exceptions.
5. Background Exceptions are covered in chapter 9 in the book starting on page 651.
Reading data from a file is shown in chapter 9. There’s a simple example shown on pages 655 – 656.
Writing to a file using the PrintWriter class is not covered in the book. Refer to the 52Exceptions.pptx lecture slides.
2
6. Assignment Read through all of the subsections in this section before you start, to make sure you understand how you must proceed with the assignment.
6.1. Create a client.cmd package Summary You will take the command-handling methods that you wrote in the CmdLoop class and turn each of them into a separate class. These command classes will be placed into a client.cmd package. (This means that the cmd package is a sub-package of the client package. This is a good way to organize your projects, placing packages within packages.)
Do this Right-click on the client package in your project, and select New → Package. For the package name, type client.cmd, then click Finish.
6.2. Create an ICommand interface Summary Each command that you place in the client.cmd package will contain a single run method that the CmdLoop.run method will call in order to invoke the command. This method will be specified by an ICommand interface.
It is common in Java to name interface files with an initial letter “I”.
Do this Create an interface called ICommand and place it in the client.cmd package.
In this class place this method declaration:
public void run(MailClient client);
6.3. Create a help command in the cmd package Summary This is the simplest command to add to the group of commands.
Do this Create a new Help class in the client.cmd package. Have it implement the ICommand interface. Copy all the System.out.print{ln} statements that you used in the CmdLoop class to display the help information, and paste those lines in the Help.run method.
3
6.4. Create a command hashtable Summary You will change the CmdLoop.run method so that instead of using an if/else ladder to check for each command, you will place the commands in a hash table. When the user enters a command, the hash table will be checked for that command string, which, if found, will give you the correct command instance to run.
Do this Create an instance variable in the CmdLoop class that is a hash table that maps Strings to ICommands. Here’s the statement that I used:
Hashtable<String, ICommand> _commands = new Hashtable<String, ICommand>();
Make that a private member variable.
6.5. Add the help command to the hashtable Summary Here I will describe how to add the help command to the command hash table that you just created. You will need to do this to other commands, so you can refer to this section if you need to.
Do this In the CmdLoop constructor, add a new table entry that maps the user command “h” to the Help command class. Here’s the statement that I used:
_commands.put(“h”, new client.cmd.Help());
Notice that I used the fully-qualified class name client.cmd.Help instead of importing client.cmd.Help and then writing new Help(). It works the same either way. I just wanted to show you that you could do this.
6.6. Check for the user command Summary The CmdLoop.run method must now check the hash table to see if the user entered one of the commands in the hash table. Right now there’s only one, the “h” command.
Do this Remove the test for the “h” command in the if/else ladder and delete the _help method.
4
At the end of the ladder, you should have a clause that looks something like this:
else if(!cmdString.equals(“”)) { System.out.println(cmd + ” not understood, type h for help”); }
Change it so that instead of just doing a System.out.println, it does this instead: 1. Retrieve the ICommand instance from the _commands hash table based on the command string that the user entered. 2. If that ICommand instance is null, then display the command not understood message. 3. Otherwise if it is not null, call the run method on that ICommand instance.
6.7. Test the help command Run the program and test it to be sure that the “h” command still shows the help contents.
6.8. Move the remaining commands Move the remaining commands except for the “q” (quit) command into the command hash table. Remove the tests for those commands in the if/else ladder, and delete all those command methods from the CmdLoop class. The final if/else statement should look something like this:
if(cmdString.equals(“q”)) { // causes loop to quit } else if(!cmdString.equals(“”)) { // bunch of stuff }
6.9. Add a Contact.save method Summary In order for the program to save all its lists (contacts, inbox, outbox) to files, the instances in the lists must be saved to files. I usually like to work from the bottom up, meaning first I get the simplest part to work, and then I build on top of that.
This method will save some of the contact information to a PrintStream, either the nick name or the email address. This will be useful for when Message instances are stored into a disk file: this is because a Message is created from either a nick name or an email address, not a complete Contact instance.
Do this This method returns nothing, and takes a PrintStream as an argument. This is the stream to
5
which the contact information will be written.
Check to see if the nick name for this contact is in the address book. If it is, then write just the nick name to the file. Otherwise, write just the email address to the file.
Since a Contact does not normally have access to an address book, you will need to make this a parameter of the method.
6.10. Add a Contact.saveFull method Summary This method will actually write all the information for a contact to a file. This method is the one the AddressBook will use to store contacts to a file.
Do this Write this method. It returns nothing and takes a PrintStream as an argument. It prints each field of the Contact to the print stream, one field per line.
6.11. Add an AddressBook.save method Summary This method saves every Contact in an AddressBook to a disk file in such a way that it can easily be read back by a load method that you’ll write later.
Do this This method returns nothing and has a String file name as a parameter.
Create a new File instance using the file name. Then create a new PrintStream instance using the File instance. Save each Contact instance (use Contact.saveFull) to the print stream.
Close the print stream when the loop completes.
An exception might be thrown when creating the PrintStream. Enclose all the statements in the body of this method in a try clause, and catch the exception that may be thrown. If an exception is caught, display the message “AddressBook unable to save to file ” followed by the file name.
6.12. Create a save command Summary The save command will save all the mail client’s information, the inbox, outbox, and address book, into a file. The program can then be exited and restarted, and the
6
information can then be loaded back in using a load command that you will write later.
Do this Create this command. Be sure to add the “sv” command to the command hash table.
Before you write statements in the run method, create a new symbolic constant in this class that represents the name of the file to save the contacts into. I did it like this:
public static final String CONTACTS = “Contacts.txt”;
Now instead of using the string “Contacts.txt” when you need to refer to the name of the contacts file, use the word CONTACTS. This will become more useful when you create the load command later.
This command simply calls the save method on the address book. Use CONTACTS as the name of the file. Later you’ll have it also save the inbox and outbox.
Test it Check to see that the save command works. Run the program and then type “sv”, then quit the program. Click once on the project folder in Eclipse and hit F5 to refresh the file list. You should see Contacts.txt file appear. Open it. You should see three lines with your contact information. The file probably has four lines in it, though, where the last line is empty.
6.13. Add a Message.save method Summary This method saves a single Message instance to a disk file in such a way that it can easily be read back by a load method that you’ll write later.
Do this This method takes a PrintStream as an argument and returns nothing.
Save the from & to contacts to the PrintStream. Use the Contact.save method to do this (remember that it’s an instance method in the Contact class, even though I’ve written Contact.save). Calling that method requires that you give it an address book as an argument, but a Message instance doesn’t know anything about an address book. Add the address book as a parameter to this method so that you can use it when you save the contacts.
Then print the three remaining fields of the message to the print stream.
7
6.14. Add a Mailbox.save method Summary This method saves each message in a Mailbox to a disk file in such a way that it can easily be read back by a load method that you’ll write later.
Do this This method returns nothing and has a String file name as a parameter.
Create a new File instance using the file name. Then create a new PrintStream instance using the File instance. Save each Message instance to the print stream. You will need to tell the message what address book to use, so make the address book a parameter to this method because a Mailbox instance does not know anything about an address book.
Close the print stream when the loop completes.
An exception might be thrown when creating the PrintStream. Enclose all the statements in the body of this method in a try clause, and catch the exception that may be thrown. If an exception is caught, display the message “Mailbox unable to save to file ” followed by the file name.
6.15. Modify the save command Have the save command save the inbox and outbox. Create named constants for the file names of the inbox and outbox, and use these constants just like you did for the contacts file name.
6.16. Test the save command Run the program: add a new contact or two, compose a new message, do a send/receive to move the message into the inbox, then compose another message so that the outbox has a message in it, then save everything.
In Eclipse, click on the project folder once and then hit F5 to refresh the file list. You should see the Contacts.txt, Inbox.txt, Outbox.txt (or whatever you named them) files appear near the bottom of the file list.
6.17. Add a Contact.loadFull method Summary This method will load data for a single contact from a scanner. It is assumed that this scanner is already attached to an open file instead of to the keyboard. Reading a contact’s information from a file is identical to that for a keyboard, except you don’t need to prompt
8
the user for what to type in next because the information is already in the file, waiting to be read.
Each contact takes up three lines of the file, like this:
jeffm@engr.uconn.edu Jeff Meunier jeff
One complication with this method is that you don’t want to create a new Contact instance until after you know that you have read all three lines from the file. That means that the Contact instance associated with the data in the file won’t be created until the reading from the file completes, which means that this can’t be an instance method.
Do this Write this method. It should be a static method. It returns a Contact. Its parameter is the Scanner from which to read the three lines of data.
The method must work like this: 1. Read three lines from the file: one for email address, one for full name, and one for nick name. 2. Create a new instance from those three strings. 3. Return that new instance.
Note that this method creates a new instance even though it’s not an instance method.
Put all those statements inside a try block. Below that, catch the exception that might happen (let Eclipse tell you what the exception is called, but don’t let Eclipse correct the problem). If the exception is caught, return null.
6.18. Add an AddressBook.load method Summary This method loads all the contacts from the contacts file, creating a new Contact instance for each one.
Do this Write this method. It returns nothing. Use only those parameters that are necessary. You can determine this as you write the method.
When reading contacts from the file, add all the contacts to a new ArrayList, not to the one stored in the member variable. If all the contacts load successfully, then replace the ArrayList in the member variable with this new one.
9
You will need to create a new File instance, then create a new Scanner from that file. Use that scanner when you call Contact.loadFull.
This method must read contacts from the file by calling the Contact.loadFull method until that method returns null. Each time it reads a contact that is not null, it must put that contact in the new contact list.
An exception might be thrown when creating the Scanner. Enclose all the statements in the body of this method in a try clause, and catch the exception that may be thrown. If an exception is caught, display the message “AddressBook unable to load from file ” followed by the file name.
If the complete list of contacts was loaded without error, then store the new array list in the _addresses member variable.
6.19. Create a load command Summary The load command will load all the mail client’s previously saved information.
Do This Add a “ld” command. This command will cause the program to load the address book, outbox, and inbox.
Right now only the address book can be loaded (you haven’t written methods to load a mailbox yet). Have it load the address book by calling the AddressBook.load method on the existing address book instance. You will need to tell it the file name to use, which is simply Save.CONTACTS. (Literally: type Save.CONTACTS for the file name. It’ll work. You’ll see.) Even though you’re loading and not saving, the file name is the same, and this way the file name is stored in a single place. If you want to change the file name later, you need only change it in the Save class.
Test this method to be sure it works: delete an address from the address book, then use the load command. The address should be restored, as long as it has already been saved to the file.
6.20. Add a Contact.load method Summary Note that a message is stored in the disk file in this way (I’ve labeled each line in brackets, but the bracketed parts don’t exist in the file):
10
[from] jeff [to] someone@somewhere.com [subj] hi [text] this is a test [time] Fri Apr 24 14:03:57 EDT 2015 Thus, the Contact.load method will be used to convert the from and to lines into Contact instances.
Do this Since a Contact instance can’t be created until after the line is read from the file, and only if the line is read successfully from the file, then that means that this method can’t be an instance method. It’s the same issue that there was for the Contact.loadFull method.
This is a static method that returns a Contact and has a Scanner parameter.
Inside this method, read a single line from the scanner. If the line is not null and the length of the line is > 0, then do this: • Determine if the line contains an email address, the same way you did for the compose message command. If it does, then just create a new Contact instance with that email address and return it from this method. • If the line does not contain an email address, then assume that it’s a nick name that can be found in the address book. Search the address book for that nick name (add it as a parameter to this method), and return that contact even if it is null. • Otherwise if the line is null or the string has length 0, then just return null. You will need to catch an exception. If an exception is caught, just return null without displaying a message.
I was able to use just a single return statement in this method. Can you figure out how to do that, too?
6.21. Add a Message.load method Summary This method loads an entire message from a disk file.
Do this Have this method load the two contacts, the subject, the text, and the time from a scanner. This method is static and it returns an instance of Message. You’ll need to determine what parameters to use.
Recall again how a message is stored in the file: [from] jeff
11
[to] someone@somewhere.com [subj] hi [text] this is a test [time] Fri Apr 24 14:03:57 EDT 2015
After you load each contact, check to see if it’s null. If it is, then immediately return null from this method.
Load the next three lines (subject, text, and time) as strings. The time will need to be converted into an actual Date instance. These next lines will do that conversion. Copy & paste into your method.
SimpleDateFormat sdf = new SimpleDateFormat(“EEE MMM dd HH:mm:ss zzz yyyy”); Date date = null; try { date = sdf.parse(dateString); } catch(ParseException e) {}
After that, create a new Message instance from the information that you now have. Notice that the message’s time stamp will be wrong: it will be set to the current time and not the time that’s stored in the file. Now you must set the message’s time stamp to be the Date instance that you just parsed. Do that by assigning the date directly to the message’s member variable.
Don’t forget to return the message.
6.22. Add a Mailbox.load method Summary This will work a lot like the AddressBook.load method works. This method loads all the messages from a file, creating a new Message instance for each one.
Do this Write this method. It returns nothing. Use only those parameters that are necessary. You can determine this as you write the method.
When reading messages from the file, add all the messages to a new ArrayList, not to the one stored in the member variable. If all the messages load successfully, then replace the ArrayList in the member variable with this new one.
You will need to create a new File instance, then create a new Scanner from that file. Use
12
that scanner when you call Message.load.
This method must read messages from the file by calling the Message.load method until that method returns null. Each time it reads a message that is not null, it must put that message in the new message list.
An exception might be thrown when creating the Scanner. Enclose all the statements in the body of this method in a try clause, and catch the exception that may be thrown. If an exception is caught, display the message “Mailbox unable to load from file ” followed by the file name.
If the complete list of contacts was loaded without error, then store the new array list in the _messages member variable.
6.23. Modify the load command Have the load command load the inbox and outbox after it loads the address book.
6.24. Test everything Make sure all the commands work.
6.25. Export to runnable Jar file Summary Several of you have asked me if there’s a way to distribute your Java projects as standalone programs without having to run them from Eclipse. This is how you do it.
Do this 1. Right click on the project folder in Eclipse. 2. Expand the Java folder in the window that pops up. 3. Choose Runnable JAR file. 4. Click the Next button. 5. For Launch configuration, expand the list and choose Main – CSE1102MailClient_2, or whatever you named yours that looks similar to that. Be sure you export this second email client project and not the first one. 6. For Export destination, click the Browse… button and choose the desktop, and name the file emailClient.jar. 7. Click the Finish button.
You may be able to just double click on the jar file on your desktop to start up the program.
13
If that doesn’t work, then do this: Mac: 1. Open Terminal. 2. Type cd Desktop 3. Type java -jar emailClient.jar Windows: 1. Open Command Prompt. 2. Type cd Desktop 3. Type java -jar emailClient.jar
Note that if you try to load the address book, inbox, and outbox files, it will look for them on the desktop. If you save files, it will put them on the desktop.
7. Report Create a Microsoft Word or OpenOffice Word file (or some other format that your TA agrees on — ask him or her if you are not sure). Save the file with a .doc or .docx format.
At the beginning of the document include this information:
Project title goes here CSE1102 Project project-number, semester Your name goes here The current date goes here TA: Your TA’s name goes here Section: Your section number goes here Instructor: Jeffrey A. Meunier
Be sure to replace the parts that are underlined above.
Now create the following three sections in your document. 1. Introduction In this section copy & paste the text from the introduction section of this assignment. (It’s not plagiarism if you have permission to copy something. I give you permission. 2. Output Run your program and copy & paste the output from the command window here. Demonstrate that each of the commands works. You do not need to write anything. 3. Source code Copy & paste the contents of your Java file(s) here. You do not need to write anything.
14
8. Submission Submit the following things things on HuskyCT: 1. Your exported Eclipse project. (but not the runnable jar file, if you created one) 2. The report document. If for some reason you are not able to submit your files on HuskyCT, email your TA before the deadline. Attach your files to the email.
9. Grading Rubric Your TA will grade your assignment based on these criteria: • (2 points) The comment block at the beginning of the Main class file is correct. • (10 points) The program displays the correct output and uses the correct calculations to generate the answers. • (4 points) The program is formatted neatly. • (4 points) The document contains all the correct information and is formatted neatly.
10. Getting help Start your project early, because you will probably not be able to get help in the last few hours before the project is due. • If you need help, send e-mail to your TA immediately. • Go to the office hours for (preferably) your TA or any other TA. I suggest you seeing your own TA first because your TA will know you better. However, don’t let that stop you from seeing any TA for help. • Send e-mail to Jeff. • Go to Jeff’s office hours.