Muppet Directory demo app

This application demonstrates the use of the Java XML libraries that we discussed in class. I am providing it for you because I think that the Java XML libraries are somewhat unpleasant to deal with. You may use this code to help you understand Java’s XML functionality, and you may borrow code from this application and reuse it in your own 20 Questions final project.

Please note that if you borrow code from this application, even if you modify said code, you MUST note in your source code comments that you have done so. If you fail to do so, we may mistakenly flag your work as plagiarized! At the top of each section of borrowed code, please write “Borrowed and modified from in-class Muppet Directory application.”

Note that this application does not include a .java source file for the BST (i.e., binary search tree) class. Instead, I’ve included a compiled .class binary.

Download the code ZIP file here

Instructions for running

Unzip the ZIP file

Once you’ve downloaded the file above, either use your GUI to unzip the file (depends on your OS, but usually involves something like double-clicking on the ZIP file icon), or use your terminal. E.g.,

dbarowy$ unzip MuppetDirectory.zip

On my Mac, a lot of stuff prints out:

Archive:  MuppetDirectory.zip
   creating: MuppetDirectory/
   creating: MuppetDirectory/bin/
  inflating: MuppetDirectory/Directory.xml  
   creating: __MACOSX/
   creating: __MACOSX/MuppetDirectory/
  inflating: __MACOSX/MuppetDirectory/._Directory.xml  
   creating: MuppetDirectory/lib/
  inflating: MuppetDirectory/lib/BST.class  
   creating: MuppetDirectory/src/
  inflating: MuppetDirectory/src/Directory.java  
   creating: __MACOSX/MuppetDirectory/src/
  inflating: __MACOSX/MuppetDirectory/src/._Directory.java  
  inflating: MuppetDirectory/src/PeopleIO.java  
  inflating: __MACOSX/MuppetDirectory/src/._PeopleIO.java  
  inflating: MuppetDirectory/src/Person.java  
  inflating: __MACOSX/MuppetDirectory/src/._Person.java  
  inflating: MuppetDirectory/src/XMLParseException.java  
  inflating: __MACOSX/MuppetDirectory/src/._XMLParseException.java

After which, you can cd into the new MuppetDirectory folder.

dbarowy$ cd MuppetDirectory
dbarowy$ ls -al
total 8
drwxr-xr-x    6 dbarowy  staff   204 Apr 19 15:17 .
drwx------+ 136 dbarowy  staff  4624 Apr 19 15:36 ..
-rw-r--r--    1 dbarowy  staff   630 Apr 19 12:18 Directory.xml
drwxr-xr-x    2 dbarowy  staff    68 Apr 19 15:19 bin
drwxr-xr-x    3 dbarowy  staff   102 Apr 19 15:17 lib
drwxr-xr-x    6 dbarowy  staff   204 Apr 19 15:16 src

Now you’re ready to give it a try.

Compile the Muppet Directory app

Assuming that you are in the MuppetDirectory folder, do the following:

dbarowy$ javac -d bin -cp lib src/*.java

This runs javac on the source files in the src folder, using the BST.class library found in the lib folder, and puts the newly-compiled application in the bin folder.

Run the Muppet Directory app

Now, run the application using the following:

dbarowy$ java -cp bin:lib Directory Directory.xml

Note that this is a little different that what you’ve seen before because we now have .class files in two places:

1. The BST.class file is in the lib folder, and
2. The other .class files that you just compiled are in the bin folder.

The -cp bin:lib tells the Java runtime to look in both places for the required compiled .class files.

If you’ve done everything correctly, you should be greeted with the following text:

Welcome to the Muppet Company Directory!

Reading company directory from disk...

Please choose an option:
1. Search for an employee by last name.
2. Add an employee to the directory.
3. Print entire employee directory.
4. Quit this program.

Enter a number:

Look at the code

1. BST.class
   • Sorry, you can’t look at this. But you should know that it has two generic variables, K, and V.
   • K represents the class used for the key. This class must be Comparable.
   • V represents the class used for the value. Because we have a separate key type, this class need not be Comparable.
   • The BST<K,V> class comes with one constructor, with the signature BST(K key, V value).
   • The BST<K,V> class also comes with a static insert method
2. Directory.java
   • This is the main application class, which has the main method and some other helper methods that print menus and read user input.
3. Person.java
   • This is more or less the Person class we’ve been reusing throughout the semester. I added an email field and changed the toString method, but it is otherwise the same.
4. XMLParseException.java
   • This is a custom exception that I defined to signal that something went wrong. Things can go wrong in lots of places when you read, parse, traverse, and write XML, so this is a catch-all exception that I can throw. A better application would catch this exception and do some kind of recovery action, but hey, I’m a lazy programmer.
5. PeopleIO.java
   • This is where most of the goodies are hidden:
   • public method readFromFile: reads a file from the given filename string, creates an XML document tree, traverses it, converts each person subtree into a Person object, and then inserts each Person into a BST<String,Person> which it returns.
   • public method writeToFile: reads the BST<String,Person> by traversing it in-order to build list of People, which are then converted to XML document nodes, and then written to filename. Note that I also set some Transformer properties to ensure that the XML written to disk is formatted nicely for human consumption.
   • There are also a couple private methods to help with reading and writing, mostly traversal-related code. Note that all of this code is specifically written to work with the MuppetDirectory’s Directory.xml data. Your 20 Questions final project will need to encode data differently, so you will likely find that this code is of limited reuse for the final project. E.g., you may need to parse recursively, like you did in the labs. That said, please use it as inspiration for how to work with Java’s XML functions. Please also refer to the Lab #9 and Lab #10, which also had you working with XML.

Look at the XML

The Directory.xml file contains the saved Muppet directory. You can open this file in your code editor, look at, and modify it. This is one of the advantages of using a text-based database format like XML as opposed to a binary database file. There are also a few downsides, but you’ll likely learn about those if you take a Databases class.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<people>
  <person>
    <fname>Big</fname>
    <lname>Bird</lname>
    <tel>555-555-444</tel>
    <email>bird@muppets.com</email>
  </person>
  <person>
    <fname>Miss</fname>
    <lname>Piggy</lname>
    <tel>555-555-2121</tel>
    <email>piggy@muppets.com</email>
  </person>
  <person>
    <fname>Kermit</fname>
    <lname>the Frog</lname>
    <tel>555-555-1212</tel>
    <email>kermit@muppets.com</email>
  </person>
  <person>
    <fname>Oscar</fname>
    <lname>the Grouch</lname>
    <tel>555-555-3333</tel>
    <email>oscar@muppets.com</email>
  </person>
</people>

This application has an important flaw

The database is written out from an in-order traversal of the BST<String,Person> data structure. The next time the application is started, it reads from the stored XML file. What kind of tree does this produce? How can the code be fixed so that this doesn’t happen? You should think about this because I may ask you a question like this on the final exam (HINT HINT HINT).