Project 4 — You've Got Mail, Round 2.5! Assigned Tuesday, November 22th Program Due Wednesday, November 30th at 11:59pm Weight 7% Updates

Objectives

1. To gain experience handling exceptions
2. To gain experience creating interfaces
3. To gain experience with Java generics

Project Overview

In this augmentation of your mail client application, you will add searching capabilities to your system. Furthermore, you will do it in a way that will exercise your knowledge of interfaces, generics, and exceptions. You will:

• Add a "search" command to your program that will have two modes: searching the header fields, and search the body text;
• Add the searching functionality to your MailRepository hierarchy using interfaces and generics;
• Use exceptions to indicate failed searches.

This is a relatively simple, tightly-scoped project, and should take only a modicum of time to complete. Also, we will not be providing any utility code, so that is one less thing to deal with.

Project Requirements and Specification

This project comprises 4 simple parts:

Part 1: Adding a SEARCH command to your program

• search body <str>
  This command will search the bodies of all email messages for a given string. The remainder of the line after the "body" keyword should be used as the search string, so it may include spaces; however, make sure you strip any leading spaces.
• search header {from|to|subject|sentdate} <str>
  This command will search all email messages for some matching header field, specified by the user. As with the body text search command, the remainder of the line, after the keyword specifying the header field, should be used as the search string, so it may include spaces; however, make sure you strip any leading spaces.

To implement this in your updated execute() method and its helper methods, you must add code to parse the arguments, package it up as either: a String for body text searches; or a MessageHeader object for header searches; and eventually call one of the two overloaded search methods described in Part 2 below. Note that although the method definitions below declare their first parameter as type Searchable<> or StringSearchable, you will be calling them with your MailRepository reference variable as the actual argument. Parts 3 and 4 below will explain the other changes that will make this work. (Note: in Proj3, you were supposed to declare your reference variable to be of type MailRepository, even though you actually constructed an instance of FileMailRepository-- not only is this good style, but important for Proj4, so correct this if you didn't do it that way in Proj3)

For the header search option, look ahead to Part 4 below to see what the semantics of the mail search methods are, so that you can figure out what your parser must do in terms of initializing the MailHeader object.

Methods in the MailRepository hierarchy will return an array of ints, indicating the indices of any matching items. Both versions of SEARCH should use this returned list of mail item numbers to generate a header listing, much like what the LIST command outputs (hint: modularize and reuse!). Note: It is especially important to include the index numbers in the output is important here!

Don't worry: other than the parsing, there is little other new code here: the MailRepository changes in Part 4 do most of the work for the actual searching. likely (hint, hint!)) will then use to fetch and display header listings for.

Line count: 20 new lines + minor changes to old code

Part 2: Adding search methods to EmailClient()

    private int[] searchMailFolder(Searchable<MailHeader> mailFolder,
                            MailHeader header) {
        return mailFolder.searchFor(header);
    }

    private int[] searchMailFolder(StringSearchable mailFolder, String pattern) {
        return mailFolder.searchFor(pattern);
    }

That's it for Part 2!

The purpose is to force you to use interfaces and generics, in an only slightly-contrived setting. The above code will force certain constraints on your design and implementation in Parts 3 and 4.

Line count: 0 new lines to write, since I provide the new code

Part 3: Creating the Searchable<> and StringSearchable interfaces

It should be obvious from the methods given above that Searchable and StringSearchable are Java interfaces, Searchable being a generic one, at that. (The reason for creating these two similar interfaces will be explained in class—incentive to show up.)

Each interface definition will consist of a single method declaration, for a method named searchFor() that takes one parameter; let's call it "item". For the declaration of searchFor() in the StringSearchable interface, the parameter "item" should be declared to be of type String. For the generic StringSearchable<> interface, searchFor()'s "item" parameter should be declared using the generic type paramter.

Line count: 2 new interface files, 2 lines each

Part 4: Adding searching to the MailRepository class hierarchy

This, in turn, implies that either MailRepository, or any of its concrete subclasses (like FileMailRepository), must implement the methods declared by the interfaces. Looking into my crystal ball, I would recommend implementing the methods in the concrete subclass FileMailRepository, since you have no idea how network mail repositories might work.

To implement this, then, you will add two overloaded searchFor() methods to FileMailRepository, one to search the body for a string, and another to search the headers. The header search will receive a MailHeader as a parameter, and will match any non-empty (i.e., not null or "") String field. So, you should check each of the four header fields, and if there is a real search string in there, you should scan for it in the corresponding header field for each mail item. Your code can assume only one of these fields will be non-empty.

In both cases, search boils down to calling the appropriate String method to see if the search string is found in the actual header or body string.

For your searchFor() method(s), we are adding one more restriction to make the project a better learning experience:
In your searchFor() method implementation(s), you are not allowed—for this project—to use any class reflection operators or methods.
That means you cannot use instanceof, or getClass(), or in any other way take an instance and try to figure out the actual object class and do conditional logic. Why will become clear later.

Line count: 20 lines of code for searching bodies, 30 lines for searching headers

Part X: Practice good programming habits

You are not to use any classes other than those in the standard Java libraries, and those specifically provided by me, without first checking with me.

Provided Classes and Sample Files

Project Hints and Notes

1. No hints or notes yet. Stay tuned...

Sample Output

Extra Credit Option

There are no extra credit options for this project.

Grading

The standard grading rules will apply to this project.

Project Submission

Important Note:
When I provide any .jar files for the project, unless you are an expert with JREs and classpaths, the easiest process is to unpack the class files into your tree. To do this, from the same directory as above, just type:

jar xf proj3UtilLib.jar

where you would replace "proj3UtilLib.jar" with whatever jar file you are using.

To submit your project, type the command

Do not submit the provided library or test input file--we have those already :-)

More complete documentation for submit and related commands can be found here.

Remember -- if you make any change to your program, no matter how insignificant it may seem, you should recompile and retest your program before submitting it. Even the smallest typo can cause errors and a reduction in your grade.