HW1: People Sorter

25 points; due Mon 3/28, 15 minutes before class.

Goals

To build a non-trivial program with Java, and to work with the List ADT.

Setup and Requirements

The code that you write for this assignment will build on top of the List ADT that we saw in class. The three files you will need are:

Every source-code file you turn in must have your name, date, etc. in a comment at the top, must have Javadoc comments throughout, must use good style (in comments too), and must attribute your sources. Please check the syllabus for more details, or ask on Piazza.

Specification

For this assignment, you will write a program that reads from a text file representing a sequence of people. Your program will need to represent each person as an instance of a class Person. It will need to convert the text file data into a List<Person>, sort the list, and print the list out in alphabetical order. This will give you practice working with the List ADT, String, File, Scanner, loops, and simple classes.

Note that it is a requirement of this assignment that you use the List ADT and implementation that I provided above.

The input file format

Each line of the input file will represent a single person via a comma-delimited list, like so:

family-name,given-name,year-of-birth,month-of-birth,day-of-birth

For example:

Rowling,J.K.,1965,7,31
Bunny,Bugs,1940,7,27
Obama,Barack,1961,8,4
Gaga,Lady,1986,3,28
X,Malcolm,1925,5,19
Bush,George,1946,7,6
Merkel,Angela,1954,7,17
Bush,Vannevar,1890,3,11
Bush,George,1924,6,12
Madonna,,1958,8,16

Note that we consider “Madonna” to be Madonna's family name (last name), not her given name (first name).

The command-line syntax

Your main method should be structured so that the program expects a single command-line argument specifying the path of the input file. Thus, I would be able to run your program like so:

java PeopleSorter people.txt

if I had a properly formatted text file called people.txt in the same directory as Person.java, or

java PeopleSorter data/morepeople.txt

if morepeople.txt was in a subdirectory called “data”. (Note: there's nothing special you have to do to handle these two cases differently. File will do the right thing in both without you having to think about it.)

If no command-line argument is supplied, your program should print out a usage message, telling the user how to call your program correctly. For example:

> java PeopleSorter
Missing required argument.
Usage: java PeopleSorter <file_path>
 - file_path: the path to a plain-text file describing a set of people, one per
   line, with comma-separated fields last_name, first_name, year, month, day.

The expected output

Your program should print to standard output (i.e. System.out) one person per line, alphabetized by family name (then given name in case of identical family names, then year of birth in case of identical names). Each line of output should look like:

given-name family-name age

For example:

Bugs Bunny 76
George Bush 92
George Bush 70
Vannevar Bush 126
Lady Gaga 30
Madonna 58
Angela Merkel 62
Barack Obama 55
J.K. Rowling 51
Malcolm X 91

Note that “Madonna” doesn't have a space before it.

For the purposes of this assignment, you may consider a person's “age” to be his/her/its age on Dec 31, 2016. If you want an extra challenge, of course, you should feel free to explore Java's built-in date-handling libraries.

Code Notes

Keep modularity in mind as you design your code, providing methods to encapsulate the main services you want from your Person objects. For example, you might organize your Person class like so:

public class Person {
  private String givenName;
  private String familyName;
  private int yearOfBirth;
  ...
  
  public Person(String gName, String fName, int year, int month, int day) {
    // Initialize the instance variables here.
    ...
  }
  
  public int age() {
    ...
  }
  
  public String getFullName() {
    ...
  }
  
  ...
}

A static-method-only approach to PeopleSorter might look like the following. The point here is to 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.

public class PeopleSorter {
  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 loadPersonList to build a List of Person objects 
    // from the input file.
    String filePath = args[0];
    List<Person> personList = loadPersonList(filePath);
    
    // Call sortPersonList
    
    // Call printPersonList
  }
  
  private static List<Person> loadPersonList(String personFilePath) {
    // Use File and Scanner to set up a Scanner for the input file
    
    // Iterate through the file, instantiating new Person objects and adding
    // them to personList.
  }
  
  private static void sortPersonList(??) {
    // ...
  }
  
  private static void printPersonList(??) {
    // ...
  }
}

There's also a more object-oriented approach to the sorting half of things: you could make PeopleSorter 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 that we might discuss in class.

Submission and Grading

Your program will probably consist of at least the files Person.java, PeopleSorter.java, List.java, MysteryListImplementation.class, and MysteryListImplementation$MysteryListIterator.class, but you may write others. You have a lot of freedom to design your solution here.

Make sure you use good, consistent style and that you write a clear, concise Javadoc comment for each class, constructor, and method. Do not include tab characters in your source code (instead indent using spaces, either 2 or 4 at a time), and limit your line length to 80 characters.

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 List.java or either of the .class files that I provided.

To prepare to submit all your files, copy all the files you plan to submit to somewhere else on your computer, copy over the three files that I provided to you, and try to compile and run your code. When you're satisfied that your submission is ready, upload it all to Canvas.

Start early, ask lots of questions, and have fun!

Assignment requirements

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

Grading

This assignment originally designed by Jeff Ondich. Thanks for sharing, Jeff!