CS11 Advanced Java - Lab 2

Boggle Boards

This week you will create the class for representing a specific Boggle board configuration. Standard Boggle boards are 4x4 grids, and each cell contains a single letter, unless the letter is "Q", in which case the cell should contain the string "Qu". Your class should be more generic than this; support NxN grids instead of just 4x4 grids. (This will allow you to provide Super Boggle boards, which are 5x5 grids, with the same code. Or, your own "Ultra-Mega-Hyper-Boggle" boards of size 20x20, if you are so inclined...)

Create a "Boggle board" class (you might call it BoggleBoard, for example) that can represent an NxN grid of cells. Each cell should be stored as a String object. You will probably want to use a 2D array of strings as the internal storage.

Here are some additional specifications for your class:

• Provide a one-argument constructor that takes a size value, and creates a Boggle board of dimension size × size.

  Your constructor should initialize the Boggle board to contain a random configuration of letters. Each cell should be initialized to either contain a single uppercase letter ("A" to "Z", minus the letter "Q"), or it should contain the sequence "Qu". You can use the java.util.Random class for generating random numbers to drive the whole process.

  (Suggestion: It would probably be best to move the "generate board" operation into a separate method that is called from the constructor. In general, each method should handle one task. Just call the "generate board" method from the constructor, after the space for the 2D grid has been set up.)

• Provide a default constructor that constructs a Boggle board with the default size of 4. (Hint: reuse your work.) The value 4 should be a Java constant, not just a magic number in your constructor implementation.
• Provide a public accessor called int size() that returns the board size. For example, if the default constructor is called, then size() would return 4.
• Provide another public accessor called String getCell(int x, int y) for retrieving the contents of individual cells in the Boggle board.
• Make sure to completely document your entire Boggle Board class using Javadoc-style comments.

The TestNG Framework

This week you will begin to create a real, formal unit-test suite for your program. We will be using the TestNG Framework to create our tests.

In general, it's a really good idea to follow some kind of "standard" naming convention for testing classes. For example, if you have a class named Foo, the class that tests Foo should be called TestFoo. For this project, follow this naming convention for your tests classes.

1. Create a test class to exercise your word-list class. Try to design your tests to cover every possible code-path within your word-list class, and so that all common usage patterns have been exercised. Here are some example tests, to get you thinking:

   • Create a word-list with the default constructor, and verify that its size is 0.
   • Create a word-list, add 3 different words. Verify that its size is 3. Verify that the "contains word" method returns true for all of those words. Verify that the method returns false for one or two other words.
   • Repeat the previous test with words that have some capital letters, and some words with leading and/or trailing whitespace. Verify that the words are properly preprocessed when they are added or checked for.
   • Create a word-list from an external data-file whose words are all distinct, and verify that the size and contents of the word-list are correct.
   • Repeat the previous test, but with another data-file that contains some capitalized words, and some words with leading and/or trailing whitespace. Verify that the words are properly processed when they are loaded.
   • Create a word-list from an external data-file whose words are not all distinct, and verify that each unique word is only included once.

   And so forth. Your tests should also exercise the "add word-list" method and the "subtract word-list" method. If your test suite is not reasonably complete then you will be required to improve it. Also, each test should exercise one "kind" of functionality; you will probably have multiple assertions in each test-method, but you shouldn't test all of these things in a single test-method!

2. Use TestNG @Test annotations to mark your test methods. You can also group your tests into "basic" tests and "file" tests (i.e. tests that involve the file-loading functionality of TestNG). You could also use the expectedException parameter of the @Test annotation to verify your word-list's behavior when handed a missing file.

3. Create another test class to exercise your Boggle board class. The test suite for your Boggle board will be significantly simpler, since this class has much simpler functionality. Your test really only needs to verify a few things:

   • The default constructor constructs a Boggle board with the proper "default size." (Hint: Your test could refer to the constant you specified in your Boggle-board class.)
   • The one-argument constructor actually constructs a Boggle board with the specified size.

   • All cells are initialized to valid values. The value of a Boggle board cell is valid if it is not null, and if the value is a single capital letter in the range "A".."Z", unless the value is "Q", in which case the value must be "Qu" (capital Q, lowercase u).

     (Hint: If you build this "check values" function as a separate helper method then you can easily call it to verify 2 or 3 different Boggle board instantiations.)

Building and Running Your Tests

To build your unit-tests, you will need to reference the TestNG framework's JAR file. TestNG is installed on the CS cluster at the following path:

    /cs/courses/cs11/software/testng-6.3.1

The specific JAR-file to use is testng-6.3.1.jar. You can either specify the path to this JAR file when you invoke javac and java. Or, make your life easy and just copy the TestNG JAR-file into your local lab2 directory!

Assuming that you copy the .jar file to your local directory, this would be your compile command on Linux:

    javac -cp .:testng-6.3.1.jar *.java

Or you can set your CLASSPATH environment-variable to reference this file. On the CS cluster this would be:

    export CLASSPATH=$CLASSPATH:/cs/courses/cs11/software/testng-6.3.1/testng-6.3.1.jar

    javac *.java

(On the CS cluster, you could edit your ~/.bashrc file to include the export CLASSPATH=... line.) The next time you login or start a terminal, the updated .bashrc file will be loaded. Or, you can just type source ~/.bashrc to reload the file in your current terminal.)

On Windows this would be:

    set CLASSPATH=%CLASSPATH%;c:\path\to\testng\dir\testng-6.3.1\testng-6.3.1.jar

    javac *.java

Once your tests compile, you can run them using the TestNG command-line tool. Again, you will need to reference the TestNG JAR file in one of the two above ways.

    java org.testng.TestNG -testclass TestWordList TestBoggleBoard

Finished?

That is all that's required for this week's assignment. When you are finished, submit your source files (but not your .class files, generated javadocs, or the word-list) on csman.

Extra Credit!

Our Boggle board actually has an annoying drawback: all letters are selected with the same probability. This makes the game significantly harder to play because you can easily end up with boards that have multiple "X" or "Z" characters. If you want to make your Boggle game easier (and more fun!) to play, you can follow an easier letter distribution. Here is a letter distribution from a Boggle-clone called Loggle:

A: 8	H: 3	O: 6	V: 2
B: 3	I: 7	P: 3	W: 2
C: 3	J: 1	Qu: 1	X: 1
D: 4	K: 2	R: 4	Y: 3
E: 10	L: 5	S: 5	Z: 1
F: 2	M: 3	T: 5
G: 3	N: 5	U: 4

You can follow this letter distribution, or you can come up with your own letter distribution.

There are several different ways to generate random results using a varying probability distribution; you will probably benefit from using collections to manage the selection process.

If you add this capability to your Boggle board class, make sure to include an explanation of your technique in the Javadocs for your class.