CS 151 - Introduction to Data Structures

Homework 2

Array and Classes - Zipcode lookup

Read the program design principles and code formatting standards carefully. You are expected to adhere to all stated standards.

Overview

In this assignment you will read from a file data about every 5 digit zip code in the United States. In addition you will develop an interface that will allow you to query the data. (The data file is in CSV format. CSV is an acronym for Comma Separated Value. Most of the data files in the course will be in CSV format.)

The general idea for the program in this assignment is that you will create a class (called Place below). Instances of the Place class hold information about a single zip code. You will create a second class (called PlaceContainer) that stores all of the instances of Place in a single large array. In addition that class will have methods for searching the array. Finally, in a third class (called Main) your program will interact with a user to allow search of the zip codes.

Importantly, your program should only read the zip code file once!

After reading and storing all of the zip codes, your program should repeatedly prompt the user for a zipcode until the user enters 'q' to quit.

Here is a sample session of the user interaction:

      zipcode: 19010
      Bryn Mawr, PA
      
      zipcode: 99400
      No such zipcode
      
      zipcode: 91729
      Rancho Cucamonga, CA
      
      zipcode: q
      Good Bye!
In the session shown above, everything is from the program other than the bold text immediately following "zipcode:"; the bold text is from the user. To get input from the user, you can use the Java Scanner class as illustrated in this little program.
      import java.util.Scanner;

      public class UseScanner {
          public static void main(String[] args) {
              Scanner scnr = new Scanner(System.in);
              while (true) {
                  System.out.print("Give me a string (q to quit):");
                  String l = scnr.next();
                  if (l.equals("q")) {
                      break;
                  }
                  System.out.println("You entered " + l);
              }
          }
      }
 
Throughout this course, you may use the Scanner class ONLY for user input. DO NOT use it otherwise. (Also, there are ways to get user input other than Scanner; you may use any of them so long as they are a part of standard Java.)

Input File Format

The data file for this assignment is on the web at https://cs.brynmawr.edu/cs151/Data/Hw2/uszipcodes.csv.
The file uszipcodes.csv contains all zipcodes used in the United States. Your program should read the data from exactly this location. (More precisely, the version of the program that you submit MUST read the file from exactly this location.) If you make a local copy for your development, that is OK.

Here are the details of the data file’s format:

The first line is a special line, giving some basic info about the file, in the following comma-separated values:

<num>;,zip,city,state,population,males,females,

where the first field in the line is an integer giving you the number of zip codes stored in the file. The rest of the line contains column headers for the file. Other than the number of zip codes, this line can, and should, be ignored.

The rest of the lines come in the following format:

<zip>,<town name>,<state code>,<population>,<males>,<females>,

where the comma-separated fields have the following meanings:

zipthe 5-digit zipcode
town name of the town with the zipcode
state2-character encoding of the state name
populationpopulation in this zipcode, an integer
malesnumber of males in this zipcode, an integer
femalesnumber of females in this zipcode, an integer

Sample data (not the actual data file which has many more lines):

5,zip,city,state,population,males,females,
00501,Holtsville,NY,,,,
00544,Holtsville,NY,,,,
00601,Adjuntas,PR,18570,9078,9492,
00602,Aguada,PR,41520,20396,21124,
00603,Aguadilla,PR,54689,26597,28092,

According to the first line, there are 5 entries following the first line. In your code, create an array of exactly the size given on this line. DO NOT hard code this number into your program. Rather, read the first line and create an array whose size is given on the first line. This number may be different during testing. Zipcode 00501 belongs to the town of Holtsville, NY, for which we have no population recorded.

In this assignment, you will ignore the population numbers, and store only the zip code, the town and the state. Note that there are towns whose names have more than one word, such as “Palm Springs”.

You should definitely use the CSV reader class from Homework 1. (This is not required but is a really good idea; among other things that class knows how to open and data data from a URL.)

2 Specific Tasks

  1. Within Visual Studio Code (if you are not using VSC, do whatever you need to do here) create a new Folder. Specifically, do the following steps:
    1. Select File Menu / Close Folder
    2. Select File Menu / Open
    3. Click on CS151 in the main folder list (you should have made a CS151 folder in Lab 1)
    4. Click on the starred folder icon in the upper right (UNIX). On Macs this is "add folder" in lower left.
    5. Name the new folder "Assignment1" -- or any name that makes sense to you
    6. Click on "Create"
    7. Click on "OK"
  2. Create a class called Place to store information about each zipcode. Place should contain the following data fields: zipcode, town, state. Per data encapsulation, these fields should be private. You will need a constructor and several accessor methods in the Place class to set up the fields and to access them.
  3. The Place class should have a constructor with the following signature:
        /**
          * Creates a place with zip, town name and state
          * @param zip a 5 digit zip code
          * @param town the town name
          * @param state the state abbreviation
          */
         public Place(String zip, String town, String state)
    	
    There are many other ways you might implement the Place constructor. (You need to write the body for this constructor.) Do it this way in this assignment.
  4. Write a second class PlaceContainer that contains at least the following public methods to implement the main part of the assignment:
        /**
         * A constructor for the class. If zip codes cannot be read from the 
         * file this should fail silently, creating an instance of the class with
         * no data to search.
         * Reads a zip code file (or URL), parsing and storing every line
         * @param a string containing either the name the zip code 
         * file or a URL  for the zip code file
         */
        public PlaceContainer(String name) 
    
        /**
         * Find a Place record given a zip code
         * @param zipCode the zip code to find.
         * @return the place, or null if the zip code is unknown
         */
        public Place lookupZip(String zipCode)
    
    Implement the class PlaceContainer and the above methods. You may find it convenient to implement some other methods as well.
  5. The general idea is that the class PlaceContainer will have an protected instance variable something like:
    			  Place[] allZips;
    		
    which will get initialized and filled by readZipCodes. Then the method lookupZip will scan that array to find information.
  6. Finally, implement a class Main that contains only a main method. This method should use the methods in Place and PlaceContainer to read and store the zip code data. (It could be that in reading and storing the main method within Main will not directly use methods in Place). The main method within Main should then implement the user interaction shown above. You might also have main methods inside both Place and PlaceContainer, but these should be only validate methods within those classes.
A smaller file (of the same format), named testZip.csv, (https://cs.brynmawr.edu/cs151/Data/Hw2/testZip.csv) is available as well, in case you want to debug on a smaller dataset. Note that this file has a first line which indicates that there are only 9 zip codes in the file.

Electronic Submissions

Your submission will be handed in using the submit script.

If you write your program on computers other than those in the lab, be aware that your program will be graded based on how it runs on the department’s Linux server, not how it runs on your computer. If you are using Java 11, you will not have any problems with Java compatibility. A way you might get into trouble is, for instance, if you developed this program on your personal computer and made a local copy of the uszipcodes.csv file and hardcoded the address of that file on your computer into your program. So, be sure to change the file name to https://cs.brynmawr.edu/cs151/Data/Hw1/uszipcodes.csv before turning in your program.

Make a README

Once you have finished coding (and fully commenting your code) make a README file. This file should follow the format of this sample README. This is your opportunity to tell me what went well or poorly, what is still broken and why, etc. I will read, and often respond to, everything you write in the README.

The easiest place to write your readme is within VSC. Make a file just like a standard java file but name it README.txt then just write in it. You should start by copying the sample readme.

Submit

(Note that many of these directions are repeated for Homework 1.)

(If your Java files, Readme etc are already on the department's computers, then skip to step 8.) If you developed this program on your own computer, do the following to transfer your program to the Linux computers so you will be able to submit.

  1. Open a terminal window on your computer (a windows powershell or a Mac terminal)
  2. Connect to goldengate.cs.brynmawr.edu. To connect:
                      ssh YOURUNIXNAME@goldengate.cs.brynmawr.edu
                
    Enter your Unix password when prompted
  3. On the linux computer:
                      cd CS151
                      mkdir a2
                
    You made the CS151 directory in Lab1. You can change a2 to whatever you like, the directions below assume a2.
  4. Leave this terminal window open and connected to Linux, you will use it again in a couple of steps
  5. Within VSC open a terminal by going to the Terminal menu and selecting "new terminal"
  6. In the Terminal inside of VSC you should be in the directory containing your program. Enter
                      scp * YOURNAME@goldengate.cs.brynmawr.edu:CS151/a2
                
  7. You should get messages on screen showing that each file in this directory has been copied.
  8. Be sure that you are in the correct place and have all of the files you need. Back in the Terminal you opened on the Linux machines (in step 2)
                      cd ~/CS151
                      ls a2
                
    This should show a list of of the files that you want to submit.
  9. When all of the files are in the a1 directory and you are still in the cs151 directory
                      /home/gtowell/bin/submit  -c 151 -p 2 -d a2
                
    This says to submit for project 2 (-p) everything in the directory a2 (-d) for the class 151 (-c). You should see listing of all the files you submitted and a message that says "success".
  10. You can submit multiple times. I will grade only the last submission -- unless you tell me otherwise. The submission process attaches a timestamp so I know when you submitted (down to the second). The closest submission I have ever received to the deadline is 7 seconds.

If the submission deadline is approaching and you cannot get this process to work, send email gtowell@brynmawr.edu with all of your files attached. There will be a penalty for using email submission.

The submission should include the following items:
1. README:
This file should follow the format of this sample README
2. Source files:
Main.java etc
3. Data files used:
Be sure to include any non-standard data files used. (This would be very unusual)
DO NOT INCLUDE
Data files that are read from the class site. Do include any of your own data files.

Approximate Grading

Grading will -- approximately -- be: