CSE143

Autumn 2002

Project 3 Step Up (Projects 3 parts b and c)

"Political Consultant"

Overall scenario: As a result of the recent census,  legislative districts everywhere have to be redrawn.  Impressed with your achievements as a computer-based historian, an international consulting firm has hired you to help their clients (local and regional governments) with a variety of mapping and political analysis problems.

As a first assignment, you were given a file describing the outline of a state, and drew the map.  Clients were so impressed that they insisted you be placed on the project for the next stage.    This time, a more detailed map needs to be drawn, which contains additional information about the state, including county boundaries and other information. 

You'll have more data than before, and will have to come up with structures to organize it.  There will be a chance to use a bit more Swing, and exercise your Programming by Contract style.  You also get to describe your design in a couple of ways

You may work with one partner.  There's enough work here that you really should find someone to work with.

Functional summary description of the finished program: A user starts the program, and has an opportunity to specify (via the command line) a text file with data representing a map of the state.  If the file does not exist, or the user doesn't supply a file, the program should show a file chooser.  If the user selects a file, processing should continue with that file.  If that file cannot be opened, or if the user presses the "Cancel" button of the file chooser, then the program should request and use an automatically created stream (this way the client can still assess your programming progress).   Assuming the data is in the proper format, the program then draws the state map and related information (details below).  The map should also be "signed" with your name and section.

What You Have to Start With

You have all the starting code for the Warm Up, as before -- plus your code from your own or your partner's Warm Up solution. We may post a partial solution to the Warm Up -- but don't wait for it before starting to work!

The Map Reader factory will be reissued with methods to create the new format, more information-rich map files.  The program you turn in should use those new methods for the randomly generated map.  During your own testing, you might want to also test files of the old type.   As before, MapMaker.java should be turned in.  When its main method is started, it should execute your entire program.

You are free to create additional .java files, too, as long as your MapMaker main operates as described to run the program.

File Format

The file format is enriched to have 3 types of lines: comments, segment descriptors, and geopolitical descriptors.

Comments: comment lines begin with //.  You can assume for the present that all comment lines are at the beginning of the file.

Segment descriptors: these are the boundary segments.  The line format is exactly as before, and is repeated here only for reference.  However, there are some changes in how the segments are interpreted.

• To make the map, the boundaries are "quantized" to line segments.  That is, the map has no curves.  Instead, there is a number of line segments which approximate the boundary.  This number may vary from file to file.
• Each line of the file represents one boundary segment.  The same segment will not be in the file more than once (see below for why there now could be more than one line with the same segment).  In each segment descriptor line, there are four double numbers, separated by one or more spaces.  The first two numbers are the x,y coordinates of one end of the segment, and the last two numbers are the x,y coordinates of the other end of the segment.  For example, the line

       10.1  200  400  82.5

• represents the segment from (10.1, 200) to (400, 82.5) on the screen.  (Programming note: some AWT and Swing methods allow you to use doubles as screen coordinates; other methods require integers.  Java will silently convert ints to doubles, but not vice-versa.)
• New: the segments now represent the boundaries of counties within the state.  (There are no special segments for state boundaries, since every part of the state boundary is also part of a county boundary).
• All the segments for a given county will be on consecutive lines of the file. There is no particular order to the segments within a particular county.  That is, segments which are adjacent in the county might not be adjacent in the file.  Likewise, counties are not in any particular order in the file.
• Note that if two counties have a common boundary segment, that segment will be in the file once for each county.  In other words, each set of county boundaries is complete and self-contained.
• Valid counties are just like valid state maps of the previous project: they are closed polygons, with no lines that cross, and no lines that are drawn off the screen.  The counties are all connected; that is, each county shares at least one boundary or part of a boundary with another county.   For the Step Up, at least, you can assume that the randomly generated maps will contain only valid counties.

Geopolitical information: Lines that begin with the string COUNTY (case-sensitive) should be interpreted as follows:

COUNTY  <county_name> <population> <county_seat_name> <x coordinate> <y coordinate>

The x and y coordinates are doubles which identify where the county seat is.   Population is a positive integer (no internal punctuation).  There will be one or more spaces between fields.  County names and city names will not contain spaces.  COUNTY lines are not in any special order.  If it makes your program simpler, you may assume that all COUNTY lines are grouped together at the end of the file, and not intermixed with other types of lines.

It is legal for a file to contain only one "county", with or without COUNTY information.  In other words, files that were valid last time as state outlines are still valid.  Except for that case, there should be exactly one COUNTY line for each graphical country.

Errors in the file of any sort should be detected and reported; the program does not have to attempt recovery.  As usual, an unexpected user or file error should not cause the program to terminate unknowingly.

Map Drawing Requirements

General requirements for map drawing are similar to the Warm Up.

Choose colors so that each component of the map is clear to see.

Outline the overall state boundary in a single color; a different color from the county (internal) boundaries.

[Not required until Part c]: For each county seat, draw a small indicator of its position, and draw its name next to the indicator.  Better do this on top of all other drawing so it is visible.  If the names overlap, don't sweat it too much (this time).

[Not required until Part c, but think about it as you do Part b]: Fill each county with a different, random shade of the same basic color (blue, for example).  The hard part is the filling, not the color selection.  [ If someone wants to write a method to pick such random shades and post it on the message board, that would be fine.]

[Not required until Part c]: There should be exactly one line of COUNTY information for each geographical county on the map.  For Part b, don't worry too much about it (although as usual, your program should not blow up unexpectedly because of this kind of error).  On Part c: make an explicit check that there is a one-to-one match.  "Extra" county COUNTY lines, or counties whose county seats lie outside the state, should be indicated on the text panel list.  Geographical counties which do not contain a county seat should be filled in with black.  It is not necessary (yet) to guarantee that each county has only one county county seat, though this may help you solve the above requirements.

New Panel!

Create and add an additional JPanel to the JFrame (you may need to enlarge the JFrame).  In the panel, place a list of all the counties: names, county seat name, and population.  Follow closely the supplied Warm Up GUI code to see what to do.  Basically, create a new class (say, InfoPanel) similar to MapPanel, and override its paintComponent method.  Leave room to display at least 15 counties.   The information does not have to scroll.  For this phase of the project, if the data overflows the panel because there are too many counties, it's OK.  [For you experimenters, it's OK to use a listbox or some other visual component -- but get it to work!]

None of the visual elements, including the map, need to be resizeable.  You can pick appropriate constant fixed sizes and stick with them.  Don't assume an unusually high screen resolution, however.

Internal Requirements

There are some requirements that your programming must meet, apart from how correctly it operates.

Continue to use Java Collections as appropriate.  Arrays may be used as well.  However, this time you may be evaluated on the appropriateness of the data structure you choose.  "Arrays are more efficient" is not necessarily sufficient reason for using arrays.  If your program uses a collection that has an iterator, you should use the iterator unless there is a darned good reason not to.

Sprinkle assertions Lavishly.  Checkable preconditions, postconditions, class invariants, loop invariants, etc. etc. should be everywhere. "Checkable" means written as assertions.  A precondition like "The array is sorted" is hard to write as an assertion, but "the array is not null or empty" is easy to assert.  Do these as you code, not at the end.  Believe me, they help the most when the code is brand-new.  So that we can check your code more easily, please identify one method in your final solution where you feel you have done an especially good job of writing assertions.  On your receipt (printout), draw a vivid box around that method, and highlight or circle every "assert".

Later in the quarter we will talk about the Model/View/Controller philosophy of design.  For now, try to keep the processing of data separate from the visible presentation of data.  For example, MapPanel is the wrong place to read in a file or compute any facts about the data.

Analytical Exercises: Due with Part c

These exercises focus on ways of expressing your design.

1. Make a class relationships diagram for your complete program.  Show has-a relationships between your classes and all classes referenced (no need to take the has-a relationships further than that).  Show is-a (hierarchy), complete, for any class you define, modify, extend, or implement.

2. Write a prose description, no more than one page in length, of the data structures which you used to solve the problem.  How many were there, and what kind?  How are they related?  What information does each hold?  Did you consider or even try other organizations?  Avoid giving code.  Imagine you were going to explain the data structures to another programmer who was taking it over from you.  This description will be turned in with the paperwork, not electronically.  You can handwrite it or make handwritten diagram if your writing is of near-printlike quality :)

Test Files and Other Testing Requirements (and Opportunities!)

• Prepare a short test file that represents a valid state with of at least three counties. Keep it small and simple!   For your own benefit of understanding, this is one of the first things you should do.
• Once the program is working, please run your program on that file, and when the map is on the screen, get a screen snapshot, print it, and turn in the snapshot with the rest of your paperwork. 
• Finally, run your program with a randomly generated file of 50 points, and make a printout of that.
• Note: your screen snapshots don't have to be in color, if color means added expense or inconvenience for you.

Label the printouts with the name of the file, as well as your name, section, and date as usual.

Service Opportunity

As before, you can prepare a test file of an actual state of the US (something more complicated that Colorado, please!) or of a foreign country.  As with previous project, include // comments identifying yourself, the source of the data, and the method of preparation.  It must be a state that no one else has done yet!

For state boundary maps (no counties), this opportunity will remain open only until the end of this week (Friday, Nov. 8, 9:00pm).  For maps with counties, the opportunity will be open for considerably longer (past the programming deadline).. 11/12: New: the file that you submit through the turnin page (when it is up) should have an extension ".text". 11/15: The deadline for submitting the test file is Sunday, November 17, 2002, 9 pm..

Click here to submit electronically.

Analytical Exercise

Either none, or to be supplied, with its own instructions and due date.

Notes on Style and Practice

As before, we ask you to use Sun's Code Conventions for Java Programmers to guide your own programming practice.

A Few More Notes

Keep the AWT/Swing part of it simple.  You won't need much beyond what was needed for the Warm Up.

Looking Ahead

Ultimately, the job will be to create congressional districts.  Being able to tell which counties are adjacent will be important for that.

Good Luck and Have Fun!

Click here to submit part b electronically.

Click here to submit part c electronically.