Project 2: Implementing new Maze generation algorithms

To Deliver: 

1. subversion repository: release 3.0, 
2. uploded code to web-cat, 
3. email to grader, answering questions 1 and 2, grader: Md Atiqur Rahman <mrahman@email.wm.edu> (Section 1), Jianhua Sun <jsun01@email.wm.edu> (Section 2).

To Download: (nothing new, you already downloaded all necessary files for homework 3) 

Due date for submission:    October 4, at noon (12.00 PM)

Drop out date:                     October 8, at 5 AM (EARLY MORNING)

Motivation

There are many different ways to generate a Maze, for a nice summary click here and read the section on Perfect Maze Creation Algorithms.

Falstad's code comes with one method that includes rooms that is implemented in MazeBuilder.java. In a previous CS301 class, students added a randomized version of Prim's algorithm that you find in MazeBuilderPrim.java. Still, we would like to have more alternatives to generate a maze. For this project, you are tasked to extend it by yet another algorithm, namely a randomized version of Eller's algorithm ( see section "Perfect Maze Creation Algorithm" here). If you are not familiar with Eller's algorithm, I would recommend this blog, this description. As with most basic algorithms, there is a place on the web with sample code like the one here. Before you go ahead and copy code from elsewhere, please recognize that the time that is necessary to understand, adjust, and debug other people's code is mostly likely about the same than implementing the algorithm yourself (and we are not talking about copyright issues here yet). To get a solid implementation, you cannot avoid the necessity to properly understand the algorithm.

What to learn from this project:

- Using inheritance to share code across classes that solve the same problem in different ways

- Exercising a test-driven approach when extending an existing code base 

- Implementing an existing algorithm in Java

- Exercising code reading abilities

Design decision

The most straightforward design is to implement your new algorithm in a subclass of the existing MazeBuilder class just like the MazeBuilderPrim class. Since inheritance allows us to formulate generic solutions in a superclass and then have subclasses for more specific cases, let's just add yet another algorithm by adding a MazeBuilderEller class that inherits from MazeBuilder.

You can add further methods and classes as you deem necessary. You can change classes and methods as well. 

Of course, modifying an existing code base comes with the risk to introduce many subtle errors. A suite of Junit test cases can help you do regression testing so see if your changes broke anything. 

If you have not done it yet for homework 3, you need to create or refine a junit test class MazeBuilderTest.java that exercises all functionality of MazeBuilder.java to check that the computed maze has all properties of a correct maze and that the provided solution encoded in the dists array is correct. Copy and adjust your MazeBuilderTest.java into a new test class MazeBuilderEllerTest.java to test your new MazeBuilderEller class.

To do list:

• Follow up on HW3: Create/Adjust/Refine a junit test case for the MazeBuilder class (MazeBuilderTest.java) as necessary.  
• Challenges are.
• MazeBuilder operates its calculations in a separate thread.  
• Figure out how the communication between MazeBuilder and Maze method works. 
• Figure out how to give the MazeBuilder thread sufficient time to perform its calculations (or terminate) before a test proceeds in your junit test cases. HINT: check Java API for Thread class.
• NEW: MazeBuilder runs a randomized algorithm. For debugging and testing it is better if we can control the random aspect such that we can reproduce failures.
• Check how this is possible with the existing SingleRandom.java class and the underlying Random library class that is used. 
• It requires you to understand the concept and next-to-nothing to program. 
• Locate where the MazeBuilder constructor lacks the code to make the random number generation deterministic and fix it. 
• HINT: This is basically one extra line of code.
• Answer Q1: how do you control that a particular call to the MazeBuilder will create the exactly same maze whenever it is performed?
• Identify which method currently generates the pathways through a maze. This method makes the Cells object a valid maze with pathways connecting all possible locations in the maze.
• The method lacks documentation, add comments to it once you figured out how it works.
• Answer Q2: classify the maze generation algorithm that Falstad implemented in MazeBuilder. How does this work? What kind of algorithm is it? ( see a list on the Labyrinth page for some possibilities).
• Create a class MazeBuilderEller.java that inherits from the MazeBuilder class, provide a skeleton method to implement the maze generation method for the MazeBuilder. 
• Use the existing MazeBuilder test cases to derive new junit test cases for your new MazeBuilderEller class, (filename: MazeBuilderEllerTest.java)
• Exercise a test-driven design: write test cases before you implement Eller's algorithm.
• Implement a RANDOMIZED version of Eller's algorithm for the MazeBuilderEller class. 
• For grading purposes:
• MazeBuilderEller.java must have a constructor method with no parameters: MazeBuilderEller().
• Eller's algorithm is implement such that it starts with a maze where all walls are up and then it selectively tears down walls with the Cells.deleteWall() method.
• You can use as many extra methods and/or new classes to achieve this as you like but make MazeBuilderEller.java being the one that is responsible for the maze generation. 
• Falstad's maze generation code also comes up with a concept of "rooms". You can include or leave out rooms from your implementation of Eller's algorithm.  
• Change the Maze application such that it accepts a parameter "Eller" and then uses your new MazeBuilderEller algorithm to generate a maze. Check if you can operate the game and see the map view from top with the solution. 
• Provide Javadoc comments for your classes and methods, in particular for MazeBuilderEller.java and MazeBuilderEllerTest.java.
• Update your subversion repository whenever you made progress and got a particular feature or method going. 
• Create a tag with a Release 3.0 before the drop out date (due date is recommended for your own sanity). Include your junit test cases in your release. 
• Upload your classes in an archive file to Web-cat.
• You can upload your classes to Web-cat multiple times in order to see how good your solution is. The last version will be used in the grading.
• We will run and evaluate your tests as well as some additional ones of our own that will test MazeBuilder.java and MazeBuilderEller.java. 
• Our tests rely on the generation of a log file that tracks whenever you call Cells.deleteWall() so please do not manipulate the log file generation as this will create real problems for the grader. 
• We will evaluate your tests to see if they performs a rigid test and if they achieve a high coverage on the tested classes.
• We will also evaluate your code documentation with Javadoc for MazeBuilderEller.java as well as test cases MazeBuilderTest.java and MazeBuilderEllerTest.java.
• Send answers to questions by email to Md Atiqur Rahman <mrahman@email.wm.edu> (Section 1), Jianhua Sun <jsun01@email.wm.edu> (Section 2).

Grading:

You will receive points for:

• Correct answers to Q1 and Q2.
• We only expect a few sentences here. No need to write a lot. 
• An accessible Subversion repository with a tagged release 3.0 
• A class design with superclass MazeBuilder, two subclasses MazeBuilderPrim (already there) and MazeBuilderEller (new) that overwrite appropriate methods from MazeBuilder.
• MazeBuilderEller implements Eller's algorithm in a randomized version to generate a maze (with or without rooms, your choice).
• Algorithm is Eller's algorithm: 
• We will evaluate this with a Junit test that relies on the log file produced with methods in Cells.java. We will log usage of the Cells.deleteWall method. You need not do anything with the logging mechanism. But you want to make sure that you use the Cells.deleteWall method when you take down walls in Eller's algorithm. 
• Algorithm is correct: 
• We will use Junit tests to see if your implementation of Eller's algorithm delivers a correct maze (there is exactly one exit, it is possible to reach the exit from each cell, etc). Correctness considerations become obsolete if your algorithm behaves like Falstad's original algorithm or Prim's algorithm. 
• Algorithm is reasonably documented: We will run Javadoc on your MazeBuilderEller class and see if methods are reasonably documented.
• Test cases for MazeBuilderEllerin file MazeBuilderEllerTest.java
• Junit tests contain non-trivial test code that covers MazeBuilder / MazeBuilderEller and contains assert statements in each test.
• Junit tests contain Javadoc comments that produce a reasonable HTML documentation such that teach test comes with an explanation on what is tested etc.
• Your implementation passes your own Junit test cases, there are no failures, no errors.
• MazeBuilderEllerTest achieves a high coverage on the MazeBuilderEller.java class