CPE 102 Program 5 - Dictionary, File I/O, Sorting and Searching

Ground Rules

No collaboration is allowed on this program assignment. Your program must be an individual and original effort. Except for any situations explicitly identified in this assignment, if any, you may only receive help from your instructor or the tutors provided by the Computer Science Department. See the Syllabus for the significant consequences for disallowed collaboration and/or plagiarism.

Due Date and Submission Instructions

Submit the following file(s) on one of the CSL servers using handin as follows:

    File(s): Dictionary.java DictionaryException.java

    touser: eaugusti

    assignment/subdirectory: 102-program05

Testing With the Provided Test Driver
  1. You should develop and use your own tests prior to using the provided test driver.
  2. Do not use the provided test driver until your solution is complete and you believe it is correct.

  3. Using the save-as feature of your browser (or wget/curl if you are a cool kid), not cut-and-paste, save P5TestDriver.java (to be published on the due date) in the same directory as all of the source files (.java files).  You will also need to download the dictionaries.zip file and extract the files it contains into the same directory that your solution's .class files are found. These dictionaries are used by the test driver to test your solution. Note that Unix and Windows systems treat end-of-line in text files differently and that some methods of transferring text files between systems and some text editors will modify the end-of-line characters. If you are developing your solution on Windows be sure to transfer the dictionaries.zip file to your Windows system, extract it there, and do not modify the files. You may view the files with a text editor but do not save any changes.

  4. Compile the P5TestDriver.java, all of your source files (.java files) and run P5TestDriver (see How to Compile and Run From the Command Line, as necessary). Remember that your code will be graded on one of the CSL servers so, to avoid unpleasant grading surprises, be sure to test on one of the CSL servers - at least once just before handing it in!

  1. To gain experience reading and writing files.
  2. To learn how to write your own application-specific exception.

  3. To implement and understand an O(N2) sorting algorithm.

  4. To implement and understand the Binary Search algorithm.

  5. To implement the Iterable<E> interface in the Dictionary class (among other things, allows someone to use the Java for-each statement with a Dictionary object).


You will be implementing a class that represents a dictionary (words only, no definitions) (also, not a python dict). When constructed the class will read the words from a text file that may be ordered or unordered. You will store the words in a java.util.ArrayList<String> and, only if necessary, sort the list using a method and sorting-algorithm that you will write. To facilitate fast word look-up you will also write a method that implements the Binary Search algorithm on the list of words. The class will also be able to write its contents to a text file (in order). Additionally, several methods of the class will throw a DictionaryException (an exception that you will write) if and when  certain specific problems occur.

Details of the Text Files

The text files, found in dictionaries.zip, contain one word per line. This means each word is separated by the newline character '\n'. Don't forget that you can actually read these files with a text editor but be sure you do not inadvertently modify them! Here are the details of the provided text file:

File Name Ordered? First Word Last Word Word Count
partialRandomDict.txt No MOTHERLY BEECHWOOD 1234


  1. Your source code must meet the Programming Guidelines.

  2. Your solution must pass all tests of the provided test driver (link and instruction provided below) when compiled and run one of the CSL servers.
  3. Do not suppress any compiler warnings. If you do, your submission may be rejected for grading or your grade marked down at your instructor's discretion.

  4. You may implement any private methods you wish to make your implementation easier and/or better.

  5. Implement an exception called DictionaryException (to be used by the Dictionary class, below). This exception must:

    1. Be a checked exception.
    2. Have no explicit instance variables.
    3. Two constructors, a default constructor and one that accepts a String parameter representing a message. These constructors must correctly make use of the super class of this exception.
    4. Must not have any other methods.
  6. Implement a class called Dictionary to this specification. Be sure to notice which methods throw a DictionaryException and when (see the detailed javadoc descriptions for the methods). You must write your code accordingly. Also notice that this specification says that the class implements the Iterable interface (a generic interface specified in the Java Standard Library). This interface specifies the iterator() method you see in the specification for the Dictionary class. You should carefully read the ArrayList Java Standard Library documentation to see it there is any support in that class that could make this task easier for you! Be sure to read the remaining specifications for important information before you begin coding!

  7. The Dictionary class may only have one instance variable, specifically one of type java.util.ArrayList<String>.
  8. You must implement your own sorting logic and may not use any sorting capabilities from the Java Standard Library. An O(N2) sorting algorithm is sufficient for this assignment and I strongly suggest that you use a Insertion Sort or Selection Sort algorithm as examples are widely available and they are relatively easy to implement. Note that your sorting code might be a good candidate to implement as a private method or methods. DO NOT just cut-and-paste code you find from the internet (<cough> stackoverflow <\cough>). You will be required to have strong knowledge of at least one of these sorting algorithms.

  9. You must implement your own Binary Search logic and may not use any searching capabilities from the Java Standard Library. The O(log N) performance of a Binary Search is required for the lookUp method of the Dictionary class. DO NOT just cut-and-paste code you find from the internet (<cough> stackoverflow <\cough>). You will be required to have strong knowledge of this searching algorithm.
Program courtesy of Kurt Mammen.