Since there are no TA Hours scheduled before the term starts, feel free to email the course staff at cs0320tas@lists.brown.edu with questions. For Boggle, we’re happy to answer even very basic questions about Linux and compiling Java code.

Overview

Welcome to CS32! This is an optional (but recommended) assignment for those who are unsure if they are prepared for CS32, want a quick refresher on their Java skills, or want to prove they are awesome. If you are well-prepared to take this course, you should be able to complete the majority of the requirements for this assignment in a few hours. A great Boggle implementation, particularly one with a complicated graphical user interface (GUI), would take considerably longer. But don't worry too much about that yet, we'll be building on this code base throughout the term in labs.

Don't know/remember how to play Boggle? Play a round or two on this website for a quick introduction.

In this assignment, your main task is implementing a single method, Board.play(). The play() method examines the Board's state and returns a Set<String> containing all of the words that can be found there according to Boggle rules. But besides implementing play(), we encourage you to read all of the provided code. It contains a lot comments and questions that you should at least be able to understand, even if you can't always answer the questions perfectly.

There are a few things about this project that will be new to you. Don't panic! First, we are using Maven to manage library dependencies and to build the project. You can certainly use an IDE like Eclipse, but all of your submissions must also compile using maven so that we can automate testing. You'll also need to use Maven to run some tools against your code. These tools will analyze your code looking for common mistakes, and code that violates our style guide. You can avoid losing easy points by listening to what these tools tell you!

Maven makes it easy to add needed libraries to your projects. In general, CS32 encourages the use of standard libraries. We've included several that we like in this build (JUnit, Guava, Gson, JOptSimple). You'll be getting to know all of them better over the course of the semester.

Another surprise is Spark. Spark is a small library that makes it easy to run a web server inside your program. This way, your program can communicate with the user by producing HTML pages (like Boggle boards) and take input from HTML forms (like word submissions). We'll be using Spark this year so that the skills you learn creating GUIs will be more directly transferrable to the real world. That means you'll be seeing CSS as a way to make your programs look good, and you'll be using some JavaScript to implement parts of your user interfaces (we'll teach you those in labs). The link above will lead you to an introduction to Spark. For more specific details of the API, check Spark's javadoc.

Setting Up

Before we start you must configure your environment to use Maven 3 and Java 8, which we have installed in the course directory.

On department machines, all you need to do is add /course/cs0320/bin to the front of your PATH variable. Your PATH variable tells your terminal where to look for various programs, like java or mvn. By putting the filepath to our bin first, you are making sure your terminal takes these programs from our bin directory, where they are up to date, rather than somewhere else. To do this, first open up the ~/.bashrc file in your home directory. Then, add a line to the end that looks like this:

PATH=/course/cs0320/bin:$PATH
in your ~/.bashrc file after any other PATH manipulation lines you may have already. This line will add our bin to the beginning of the list of paths the terminal will search through.

After you add this line, you should restart your terminal, or run the command

source ~/.bashrc
to reload the bashrc after editing and check that your path is set correctly by running
echo $PATH
You should see the course's bin directory at the front. Don't run mvn until you do that, and don't run it in a terminal that was opened before your change. To double check, run: mvn -version which should print out Maven version 3.

Look through your ~/.bashrc and ~/.bash_profile and remove any line that begins with export JAVA_HOME. Then, add this line to your ~/.bashrc

export JAVA_HOME="/course/cs0320/bin/jdk1.8.0_25"
Make sure java -version outputs 1.8 (which is commonly referred to as simply "Java 8").

If you want to develop on your own computer rather than by remotely using a department machine, you'll need to install the JDK (version 8), Maven (version 3), and perhaps Eclipse. But there are quite a few IDEs out there so feel free to work on whichever one works the best for you (e.g. IntelliJ) or none at all (e.g. emacs or vim). Check out our work from home guide for detailed information about working on your personal computer.

If you have questions, please email us!

Getting Started

For this project (and only this one) we're providing most of the skeleton code.

First, we recommend creating a work directory for cs032 work. For example, run mkdir ~/cs0320 to make a cs032 directory in your home directory. Then cd ~/cs0320. Now that you're in your work directory, you can download the boggle zip file here. If you are trying boggle from home, you can still download the boggle file.

Once you've downloaded the file, dig around for the Java files and start exploring. You should rename the jj directories to your own username. On a department machine, run:

mv boggle/src/main/java/edu/brown/cs/jj boggle/src/main/java/edu/brown/cs/$USER
mv boggle/src/test/java/edu/brown/cs/jj boggle/src/test/java/edu/brown/cs/$USER
(on a home machine, substitute your login for $USER manually).

Then make the associated changes to package names as well. Here's a handy shell command that looks for "jj" in all the java files under the boggle subdirectory. You'll need to edit them.

find boggle -name "*.java" | xargs grep jj

Keep the basic directory structure, because maven is picky about that.

Building

We supplied a maven build file pom.xml, containing our configuration for maven. Run

mvn package
to compile the project and produce an output .jar file (in the target/ directory). The first time you run mvn package, you'll see maven downloading a lot of libraries. Don't worry, that will only need to happen once.

You can run mvn clean to start fresh (which you should do after you change class or package names, for example.) For more information about maven, see the useful links at the bottom of this page.

Running

In the stencil for this project, we have provided a sample executable (./run). For all of your projects in CS32, we will expect you to turn in a similar executable. Even if you use an IDE, you must ensure that your command-line script works, as it allows the staff to run and test your code. If you take a look at that file, you will notice it's pretty straight-forward, with each line explained. Use the provided shell script run to invoke your build. For example,

./run --generate 
should output a random Boggle board.

Try invoking ./run with no extra arguments. You should get a message printed that tells provides a url like http://127.0.0.1:4567/ or http://localhost:4567/ (which are equivalent). Visit play page of the printed URL with your a web browser (i.e. http://localhost:4567/play). You can enter a list of words there, but they won't be scored properly until you implement Board.play().

Requirements

Here's what we've left for you to do:

  1. Implement Board.play() to return all legal words for the board. Words must appear in the dictionary created at the start of the Board class, and can be formed by connecting letters vertically, horizontally, or diagonally. You may not "backtrack" or "circle around" to use the same position twice. Once you're done, a command like ./run --solve=msap,tett,yate,zvoe should print all legal words for the board made up of the given four rows of letters.
  2. Test your program. In most projects, we'll ask you to write tests that show your individual classes work well (those are unit tests) and that your entire program works properly (those are system tests. We've provided some unit tests here, but we'll cover both in more depth in the first lab. For now, run mvn test to see how unit tests work (some will fail, until Board.play is properly implemented).
  3. Enhance the GUI. In later projects, you'll be creating GUIs as well, but you don't need to worry about that for now. In later labs we'll show you how to make the boggle boards look good, implement interactive scoring and timers, and so on. We won't be assuming any experience with HTML, CSS, or JavaScript before CS32 so don't worry if you have no idea how you would do that yet.

Checking your code

Normally, we expect you to write extensive test cases for your code. That's the best way to be confident that your code is correct. However, there are some tools that we've set up for you that will pick up some simple mistakes, both in formatting and in common error-prone code patterns (also known as "anti-patterns").

You can invoke these tools my running mvn site. That command tries to generate a complete website for the code being built and puts the results in the target/site subdirectory of your project. Visit the generated site by using a "file://" url. Use something like:

file:///home/jj/cs32/boggle/target/site/index.html

You'll have to change that depending on where you put your project directory. Once you open the site, you should see something like this:

At the lower left, click on "Project Reports". You should see five reports.

  1. Source Xref is a clickable version of your source code. The other reports point here to show you their results.
  2. JavaDocs is the generated documentation from the JavaDoc comments you have in your code.
  3. Checkstyle is a report generated using a set of rules that the course staff has developed for cs32 code. Until you become used to these rules, we suggest you consult this report often. You will lose points if you violate these simple code formatting rules!
  4. PMD is static checker that looks for bad programming practices.
  5. FindBugs reports on code patterns that often lead to subtle bugs. FindBugs works on .class files, not .java files, so you'll have to recompile (mvn package) before you'll see your changes in mvn site.

Some of these reports disappear if they have no errors to report. That's a good goal! The first thing we'll do when looking at your handins is to run these reports and check the output. If you leave code in your handin that violates any of these rules, expect to lose points unless you have a very good reason.

Handing In

With every project, we expect you to include a README file describing:

  • Known bugs.
  • Design details specific to your code.
  • Your testing plan — what tests did you write (unit and system), and why?.

However, you won't need to hand in boggle since it won't be graded. Good luck!

Helpful Links

Working Remotely:

  • The department's Sunlab resources will help you set up ssh so that you'll be able to login and work on department machines from elsewhere. You should follow the advice about setting up ssh, but be wary of following the advice for setting up remote desktops or access to X applications. Using GUI applications like Eclipse or a web browser will be painfully slow over a remote link.
  • Our work from home guide will help you set up for development on your own machine. This is a much better option than options like X forwarding over ssh, FastX, and XQuartz

Maven:

  • Wikipedia page - Surprisingly good overview on Maven basics, pom.xml structure, and philosophy. (Recommended Read)
  • Maven's Getting Started Guide - Official in depth tutorial if you're interested but also does some things different than what's needed for us.
  • M2Eclipse - If you're looking to use Eclipse, this is official plugin for maven integration.

Spark:

  • Official documentation for Spark. Please be aware that they use Java 8's new lambda expressions to neaten the syntax of route handlers. To avoid overwhelming you we have implemented our Boggle code without this syntax. It's up to you which syntax to use — but we want you to understand that lambda expressions are transformed to code you could write with the older syntax.