Lab 9: CVS and Swing

Logistics

General

This lab is completed as a team. Each team will have its own project directory which should be used to store a CVS repository for the group. Your team's project directory can be found at /project/c421aaNN (where NN is replaced by your team number, for example /project/c421aa02). To find your group number, use the groups command at the unix prompt. You should see the list of unix groups of which you are a member.

One person from the team will make the submission through Carmen. To ensure that everyone is clear on who will submit the lab, each team should agree on one person and should email the grader the name of that person before the lab due date. Of course, every member of the team should participate equally in the development and testing of your submission.

This lab handout includes the description of three different projects. Your team, however, should only tackle one of these projects. The decision of which project to do is up to you. The projects are of similar difficulty, have similar minimum requirements, and have similarly expandable scopes. In other words, all projects are fairly open ended! Your choice of project, then, is largely a matter of taste.

Minimum Requirements

In addition to compiling and running with basic functionality, your submission should also include: documentation in the form of javadoc HTML pages, testing code in the form of JUnit test classes, and a readme file that describes basic execution or installation instructions. In addition, you should strive to follow as many "best practices" as reasonable in your solutions including: separating interface from implementation, coding to the interface, properly using exceptions/assertions, implementing core methods, and logging. Run CheckStyle and FindBugs to find (and remove) as many violations as possible.

Rough Grading Scheme

Your grade for this lab consists of two parts: the group grade (70%) and your individual grade (30%). For the group grade, your submission is evaluated along the following general categories:

1. Correctness and functionality (30%)
2. Coding style (30%)
3. Documentation (20%)
4. Your own testing (20%)

Project Descriptions

1. Tag Cloud Browser

   A tag cloud is a list of words where the font size of each word reflects its relative importance. The list can be sorted in a variety of ways, but alphabetical order is typical. Additionally, font color can be used to reflect a relative ordering property of a particular term. Thus, a tag cloud can succinctly present 3 separate degrees of information through ordering, size, and color of the individual words. Examples of popular tag clouds for navigation include: Flickr, technorati, and del.icio.us.

   Examples of tag clouds for visualizing information include: a recent presidential debate, and a history of presidential speeches. The last example has four dimensions of information: alphabetical ordering of tags, font size, font color, and a slider at the top for browsing through time. Many good examples of visualizations involving four (or more) dimensions of information can be found at Gapminder, where colors, sliders, font/image size, and position are all effectively used for different dimensions.

   One approach for this project could be to generate html and then view that document with an off-the-shelf Swing component that renders the html appropriately.

   For this project, you implement a graphical tag cloud browser for generating and visualizing at least three dimensions of information (eg ordering, size, a slider, color, etc). The GUI of your browser should allow the user to enter between 2 and 5 file names; for simplicity, assume that all these text files are located in the same directory as your code. The program should generate a tag cloud for each given text file and should support browsing through these clouds with a slider. To help with your testing, examples of such files are available here.

   The ordering should be alphabetic. The clouds become more meaningful if certain commonly-used words (eg "a", "the", "with", etc.) are ignored. Your GUI should allow the user to enter the name of a file that contains such words; however, the browser should work even if the user does not provide such a file. The size of the clouds (ie the number of words) should be entered by the user using the GUI.

   Note that it is possible to use font color to show additional information. For example, the tag cloud for presidential speeches finds how long ago a given word reached its peak usage and brightens the recently used words while fading away words have not been used in a while. If you feel ambitious, you can implement this feature or some similar feature based on font color. However, you do not have to implement any font-color functionality in order to get full credit for this project, and you will not get extra credit for it.

2. Battleship

   Battleship is a two-player game played on square grids. Each player secretly arranges a number of ships on his/her grid and after that the game proceeds in a series of rounds. In each round, each player's turn consists of announcing a target square in the opponent's grid which is to be shot at. If a ship occupies the square, then it takes a hit. The player's opponent announces whether or not the shot hit (and sunk) one of his/her ships and then takes a turn. When all of the squares of a ship have been hit, the ship is sunk. When one player sinks all the opponent's ships, he/she wins the game and the game ends.

   For this project, you will implement a graphical Battleship program. The program should allow 2 human players (sitting at the same keyboard) to play against each other. When the program starts, each player in turn is asked to place the ships on his/her grid and the program hides the ships from view. The program should ensure that the right kind and number of ships are placed within the grid and so that they do not overlap. After that the players take turns selecting one cell in their grid (where the opponents ships are hidden) and the program responds indicating whether the shot was a miss, a hit, or a hit resulting in a ship being sunk. If all the ships have been sunk, the game proclaims the winner and displays the remaining hidden ships for the loser.

   Here are a few more specific requirements:

   • Use 10x10 square grids
   • The squares in the grids are identified by a letter (A-J for the row) and a number (1-10 for the column).
   • The program should allow (force) each player to place exactly one of each of the following ships:
     • aircraft carrier, 5 cells
     • battleship, 4 cells
     • cruiser, 3 cells
     • submarine, 3 cells
     • destroyer, 2 cells
   • The ships can be placed either horizontally or vertically and they must fit within the grid's boundaries and cannot overlap.
   • The GUI of the program should display the grids showing where all the previous shots have been fired with symbols that identify misses, hits, and sunk ships.

   There are many ways that the game could be made more flexible and user-friendly. For instance, different grid sizes could be supported and the size of the grid could be provided on the command line. The program could also allow different combinations and numbers of ships (as long as both players have the same number and types of ships). It could also be useful to allow the program to automatically and randomly place the ships, if a player so desires. You do not have to implement such functionality in order to get full credit for this project, and you will not get extra credit for it.

3. Word Mastermind

   Mastermind is a 2-person game: one player creates a secret code and the other player makes guesses. The code maker scores each guess, thus providing some information to the code guesser. A fixed number of guesses are allowed. The code guesser wins if she/he succeeds in breaking the secret code before that number is exhausted.

   The classic version of Mastermind involves codes (and therefore guesses) of length 4 and consisting of colors. A variant of this game uses codes of length 5 and which consist of letters rather than colors. A further constraint is that the code be a valid English word. Each guess receives a score (0-5) indicating the number of letters in the guess that are also in the secret code (independent of order). This variant is known as Jotto and more information can be easily found on Wikipedia.

   For this project, you will implement a graphical Jotto program. The program should allow 2 human players (sitting at the same keyboard) to play against each other. Your program should read in a file of acceptable dictionary words to check the validity of entered codes and guesses; the name of this file should be provided as a command-line option when the program is started. You can assume that the file will contain one word per line, without empty lines. One file you can use for your testing is single.txt (contains over 354,000 single words, excluding proper names, acronyms, or compound words and phrases; does not exclude archaic words or significant variant spellings; created by Grady Ward).

   When the program starts, each player enters her/his secret code using password mode — the characters should be invisible. The program should check that each of the two codes is a 5-letter word that appears in the dictionary file; if this is not the case, the code will be rejected and the player will be asked to enter a valid code. After each player enters a valid code, the players take turns and enter their guesses. The program should check that each guess is a 5-letter word that appears in the dictionary file; if this is not the case, the guess will be rejected and the player will be asked to enter a valid guess. Note that Jotto does not allow words that contain multiple occurrences of the same letter (eg "check" is not allowed because it contains two "c" letters). This property should be checked when entering codes and guesses, and invalid codes/guesses should be rejected. Finally, we will constrain all codes and guesses to contain only lowercase letters from "a" to "z"; codes and guesses that contain other characters should be rejected.

   The GUI of Jotto should show a history of all guesses that have been entered up to this point, and the results for each guess (ie number of letters that match). The game ends when one of the players guesses correctly the code of the other player, or when the number of guesses exceeds a pre-defined threshold. The threshold is given as a command-line option when the program starts.

   If you feel ambitious, you can add bells and whistles to the program. For example, during the game, a player may be able to determine that certain letters are definitely not in the opponent's code (eg when the program reports 0 matching letters). For each player, the GUI could provide a separate list of letters ("a" to "z") and the functionality to "cross out" certain letters that are clearly not in the opponent's code; this will simplify the book-keeping and will make the game more user-friendly. You do not have to implement such functionality in order to get full credit for this project, and you will not get extra credit for it.