CS 201: Data Structures (Winter 2017)

HW03: Zoo displayer

Due: Wednesday, 01/18 at 22:00

This is a pair programming assignment. If you are on a team, this means that you and your partner should be doing the entirety of this assignment side-by-side, on a single computer, where one person is "driving" and the other is "navigating." Take turns every so often who is driving; you should each spend approximately 50% of the time driving.

Review the style guide. Starting from this assignment, you will be graded on coding style.

1. Goals

To build a non-trivial program with Java that includes both text and images, and work with the List ADT.

2. Setup

The code that you write for this assignment will build on top of the List ADT and one of the implementations of List that we've seen in class. The code will also use one additional class that is not part of the Java library:

• EzImage.java

You should not make any changes to this file. The Javadoc for this class is at:

• EzImage

You can get all of the files plus a sample zoo with image files here.

It may be useful to refer to the code from class and labs. The appendices of our book may also be useful. The official Java API documentation will likely be helpful for choosing what implementation of a List you'll use, and for seeing what methods are available.

3. Specification

For this assignment, you will write a program that reads from a text file with one line for each animal in a zoo. Your program will need to represent each animal as an instance of a class ZooAnimal. It will need to convert the text file data into a List<ZooAnimal>, sort the list, and print the list with the animals sorted alphabetically in one of two forms: as a display of animal images or as a text list. This will give you practice working with the List ADT, String, File, Scanner, loops, and simple classes. It will also let you see how you can display images, moving closer to more complicated applications.

The input file format

The input file is a text file that contains 0 or more lines of animals. Each line of the input file will represent a single animal via a comma-delimited list, like so:

For example:

The command-line syntax

Your main method should be structured so that the program expects two command-line arguments: the first specifies the path of the input file and the second specifies the display method (either "picture" or "text"). Thus, if I had a properly formatted text file called ZooExample.txt in the same directory as ZooDisplayer.java and wanted to show a picture of the zoo, I would type:

If ZooExample.txt was in a subdirectory called data and I wanted to show a text output of the zoo, I would type:

(Note: there's nothing special you have to do to handle ZooExample.txt versus data/ZooExample.txt. File will do the right thing in both without you having to think about it.)

The expected output

Your program should produce output based on whether "picture" or "text" was chosen:

• picture: The program should display an image of the zoo, with the animals in sorted order (see below for details). Animals should be in one window, with images in order from left to right (see appendToRight method in EzImage).
• text: The program should print to standard output (i.e., System.out) one animal per line in sorted order. Each line of output should look like:
  animal-name species age

Sorted order for zoo animals is alphabetized by animal species, then name in case of identical species, and then year of birth in case of identical names (with older animals appearing before younger animals). Like a previous homework, I want you to write your own sort. You'll learn some additional sorting methods later this term; for now, you can try looking in your book for a sorting method if you don't remember one. However, please make sure you're not copying code directly out of the book (you should be able to explain any code you submit!), and if you rely heavily on a book example, please make sure to cite it in comments. You should not use any built-in Java sorting methods.

For example, if text display was chosen for the zoo above, the output should be:

If picture display was chosen, this zoo would look like this:

For the purposes of this assignment, you may consider an animal's age to be the number of years back from 2017 that the animal was born. For example, an animal born in 2015 would be 2.

4. Code notes

• Keep modularity in mind as you design your code, providing methods to encapsulate the main services you want from your ZooAnimal objects. Think critically about what code should be in ZooAnimal.java and what code should be in ZooDisplayer.java. This is part of the grading criteria listed below.
• You are encouraged to look at the Comparable interface, though you are not required to implements it.
• It may help to review lab01 and the split method in String.
• To compile all of the files in a folder at one time, you can run javac *.java while in that folder. The *.java means anything that ends with .java.
• While the EzImage class might look complicated at first, you should only need to use a few methods: a constructor, the appendToRight method, and show. Take a look at the javadoc to learn how to use these methods, and experiment if you're not sure! You can ignore the other methods entirely. The directory with the pictures should be in the same directory as ZooDisplayer. For instance, I have a directory called zooPics in the same directory as ZooDisplayer, and zooPics has all of my animal pictures. (Download the complete homework files to get these images: feel free to test with your own images!)
• If you have a very large zoo, you might not see all of it displayed (as it could be too big to fit in the window). You can move the left part of the window off the screen and then resize to make it wider to see that the rest of your zoo is still really there.
• You can make your ZooDisplayer object oriented or use only static methods; either design is okay for this assignment. However, you should make sure that you put major self-contained operations into separate methods. This way, the main method reads like a high-level outline of the process you're implementing, rather than being a mess of all the code in a single method. For example:
  public class ZooDisplayer { public static ?? loadZoo(String filePath) { // Read the zoo file and load animals. } public static ?? sortZooAnimalList(??) { // ... } public static ?? displayTextZoo(??) { // ... } public static ?? displayZooImage(??) { // ... } public static void main(String[] args) { // If there's no command-line argument, print a usage statement and exit. // Otherwise, use args[0] as the input file path. if (args.length == 0) { // ... } // Call the methods you defined above to load, process, and display the // zoo animals } }

  This is just an example of one organization: you are not required to follow this example, but you're welcome to.

  There's also a more object-oriented approach to the sorting half of things: you could make ZooDisplayer into a real class that carries its own state (as opposed to an otherwise empty class with a bunch of static methods in it). This has some advantages, such as being able to have multiple zoos; you're welcome to take an object-oriented approach now or to wait until we return to the ZooDisplayer in a later assignment.

• Make sure to test that your ZooDisplayer properly loads and sorts different files of zoo animals. Your program should never throw an exception or error message if given a valid filename that has a properly formatted zoo (containing 0 or more animals), including valid image file names. That is, you don't need to worry about recovering if the user gives you a file that doesn't look like the example one or if the image paths that are in the file don't actually lead to images.
• If the user doesn't properly type in "text" or "picture" as the second command line argument, display a helpful message for them about how to use your class; this is called a usage statement.
• In terms of the style of your program, you will likely find the style guide helpful. Think about making your variable names and method names descriptive, and make sure the methods and constructors take logical arguments and have comments that tell the user how to use them. Imagine that while you're in charge of these two classes, you're part of a larger organization where other programmers may use your classes. Design your program so that it will be easy for these other programmers to understand and reuse your work.
• Optional extra challenge: If you're looking for further practice on your Java skills, use try/catch blocks to fail gracefully if the file is not found or if the file is not properly formatted. You might also try to partially recover if part of a file is not properly formatted, e.g., skip improperly formatted lines.
• Optional extra challenge: Large zoos will result in windows that are bigger than your screen. Modify your zoo displayer so that if the zoo would be more than 800 pixels wide, the zoo is split into separate EzImage windows. For instance, imagine that you have 4 animals in the zoo, the first of which is 700 pixels wide and the other three are 350 pixels wide. The first animal would get its own window. The next two would be in a shared window (since 350 + 350 = 700 < 800), and the final one would also end up in its own window. If you go this route, the titles of the windows should reflect the sorted order (e.g., Zoo Photo 1, Zoo Photo 2, and Zoo Photo 3 in the example above, allowing the user to know what the correct sorted order is).

5. Submission and grading

Your program must consist of at least the files ZooDisplayer.java and ZooAnimal.java, but you may write others. You have a lot of freedom to design your solution here. Please make sure that every file you submit has your name and your partner's name at the top.

Submit all of the Java source files that you wrote that are necessary to make your program work. Do not submit any .class files for the classes that you write, and also do not submit the EzImage.java file that was provided.

To submit your files, prepare a zip (or tar) archive. Name the file [yourUsername]-[yourPartner'sUsername] (without the square brackets; this makes it easier for the grader). Double-check your zip file: copy it to somewhere else, unzip it, copy over the files that I provided to you, and try to compile and run your code. Also, make sure to not include extraneous files or directories (e.g., I don't need your image files; exception: if you want to include a screenshot of your favorite zoo display, please include it in your submission or post it to share with your classmates on Moodle!). When you're satisfied that your submission is ready, one of you should upload the zip file to Moodle.

Assignment requirements

This is a partial list of the things that we'll be looking for when evaluating your work:

• Correct command-line syntax and behavior (including naming the main class ZooDisplayer)
• File parsing
• Sorting according to all criteria described above
• Use of the EzImage class to display a picture of your zoo
• Correct formatting of output
• A full-featured ZooAnimal class to represent individual animals
• Program compiles
• Program runs correctly on test input
• Code uses the ADT implementation correctly: the name of the class implementation list appears only in the initialization of List variables, and then only on the right-hand side (just as in the example code from class)
• Encapsulation: code correctly placed in ZooAnimal.java and ZooDisplayer.java
• Style: Make sure to follow the style guide

Grading

• Assignment requirements [20 points]
• Comments, style, and design [5 points]

This assignment modified from one designed by Anna Rafferty.

Start early, have fun, and discuss questions on Moodle.