Since there are no TA Hours scheduled before the term starts, feel free to email the course staff at email@example.com with questions. For Boggle, we’re happy to answer even very basic questions about Linux and compiling Java code.
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
examines the Board's state and returns
Set<String> containing all of the words that
can be found there according to Boggle rules. But besides
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
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:$PATHin 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 ~/.bashrcto reload the bashrc after editing and check that your path is set correctly by running
echo $PATHYou 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 -versionwhich 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 -versionoutputs 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!
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
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.
We supplied a
mvn packageto 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.
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 --generateshould output a random Boggle board.
./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
Here's what we've left for you to do:
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,zvoeshould print all legal words for the board made up of the given four rows of letters.
- 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,
mvn testto see how unit tests work (some will fail, until Board.play is properly implemented).
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
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:
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.
- Source Xref is a clickable version of your source code. The other reports point here to show you their results.
- JavaDocs is the generated documentation from the JavaDoc comments you have in your code.
- 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!
- PMD is static checker that looks for bad programming practices.
- 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
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.
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!
- 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
- 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.
- 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.