CMSC 202 Project 4

Objectives

To gain experience handling exceptions
To gain experience creating interfaces
To gain experience with Java generics

Description

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

You can start by adding a SEARCH command to your main command parsing loop in EmailClient.execute(). It will have two "modes", so I will describe the two separately:

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.

Both version of SEARCH should use the returned list of mail item index numbers to generate a header listing, much like what the LIST command returns (hint: modularize and reuse!) ; including the index number in the output is important here!

Don't worry: other than the parsing, there is little other code here: the MailRepository changes in Part 4 do most of the work.

So, now, in your updated execute() method or its helper methods, you must 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 methods described in Part 2 below. Note that although the method definitions below take something of type Searchable<> or StringSearchable as the first parameter, you will be calling them with your MailRepository reference variable as the actual argument. (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.

Part 2: Adding search methods to EmailClient()

This part is easy--really! All you have to do is cut-and-paste the following two method definitions into your EmailClient class:

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

    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.

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. Each 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.

Part 4: Adding searching to the MailRepository class hierarchy

In Project 3, you created an abstract class MailRepository, and you declared your reference variables in the EmailClient to be of this type (even though you actually constructed a FileMailRepository object). The way you are now treating this reference in your implementation of Parts 2 and 3 above means that the declaration of the class MailRepository will now need to be modified to indicate that it implements some interfaces.

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 subclasses like FileMailRepository, since you have no idea how network mail repositories might work.

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 "grok" the actual object class and do conditional logic. Why will become clear later.

Part X: Practice good programming habits

As always, also pay attention to good procedural programming principles! You should still write clear, modular code. This means breaking up oversized, monolithic methods into smaller, logically divided submethods, abstracting out common, repeated chunks of logic into private helper methods, giving your variables meaningful names, etc.--you know the drill.

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

There are no additional classes or sample files necessary, other than what was provided for Project 3.

Project Hints and Notes

No hints or notes yet. Stay tuned...

Sample Output

Since your EmailClient class will not have changed much, the output should be much as it was in Project 3.

Extra Credit Option

There are no extra credit options for this project.

Grading

The standard grading rules will apply to this project.

Project Submission

Before submitting your project, be sure to compile and test your code on the GL system. See the Project Compiling section of the course projects page for details on how to run and execute your project on GL.

(Note that the above section has been augmented to cover how to get files to the GL filesystem, and how to unpack JAR files to test your program.

To submit your project, type the command

submit cs202 Proj4a MailRepository.java FileMailRepository.java <any other .java files you created> See the Project Submission page for detailed instructions.

You may resubmit your files as often as you like, but only the last submittal will be graded and will be used to determine if your project is late. For more information, see the projects page on the course web site.

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.