Assignment 3: Meet Your Match, Part 2: The Controller
Due dates:
Implementation:
Tuesday, Feb 13Wednesday, Feb 14 at 8:59pmSelf-evaluation:
Wednesday, Feb 14Thursday, Feb 15 at 11:59pm
Starter files: code.zip
1 Purpose
The goal of this assignment is to practice writing a controller. While the model in a program represents the game state, the controller “runs” the program, effectively facilitating it through a sequence of operations. This assignment mimics the style of the previous assignment, in that you are provided an interface that you must implement and adequately test. The class you implement will act as the controller and work with the model that you created in the previous assignment. This controller will “run” a game of SameGame, asking for input and outputting the game state. Since the game will still be text-based and the input/output will be limited to the console and keyboard, the notion of a “view” will be minimal in this assignment.
There will be two submissions for this assignment:
Your actual implementation of the controller and full test suite
A self-evaluation, due one day plus three hours later than the actual implementation, where we will ask you to reflect on your implementation and testing choices.
The same late-day policy as on the previous homework applies: each of these three submissions independently may use up to one late day, and you are still able to submit your self-evaluation on time even if you submit your implementation late.
You are expected to use your code from the previous assignment as the starting
point for this assignment. However, please ensure all of your new code is
in the cs3500.samegame.controller
package. Additionally, your code from
the previous assignment should remain in the cs3500.samegame.model.hw02
and cs3500.samegame.view
packages.
2 Preliminaries: Improving your view
In the previous assignment, you implemented a SameGameTextView
class,
such that its toString
method provided the desired output. This was
not ideal design, but it was convenient at the time. For this
assignment, you will refine that view to be slightly more flexible. Enhance
your class such that it now implements the following interface, which
should replace the one given in the previous assignment:
public interface SameGameView<T> {
/**
* Renders a model in some manner (e.g. as text, or as graphics, etc.).
* @throws IOException if the rendering fails for some reason
*/
void render() throws IOException;
}
This view interface is tiny, but it abstracts away the idea that views are
intrinsically String
-based.
You should then add a second constructor to your
SameGameTextView
class, that takes in both a model and an
Appendable
(see below), and implement render
such that it appends
the current textual output to that Appendable
. You should
preserve your toString
method, since it is useful, but you should
also implement this render
method —
3 The Controller interface
The interface for the SameGame controller must support the following
functionality (as an interface SameGameController
that you
should place in the cs3500.samegame.controller
package):
A method
void playGame(SameGameModel<T> model, int rows, , int cols, int swaps, boolean random)
. This method should play a new game of SameGame using the provided model, using thestartGame
method on the model that matches the inputs to this method. It should throw anIllegalArgumentException
if the provided model isnull
. It should throw anIllegalStateException
only if the controller is unable to successfully receive input or transmit output. The nature of input/output will be an implementation detail (see below). It should throw anIllegalArgumentException
if the game cannot be started.A method
void playGame(SameGameModel<T> model, List<List<T>> initBoard, int swaps)
. This method should play a new game of SameGame using the provided model, using thestartGame
method on the model that matches the inputs to this method. It should throw anIllegalArgumentException
if the provided model isnull
. It should throw anIllegalStateException
only if the controller is unable to successfully receive input or transmit output. The nature of input/output will be an implementation detail (see below). It should throw anIllegalArgumentException
if the game cannot be started.
Before you implement your controller (see The Controller implementation below), you should first work through examples for it.
A suggestion about workload management: You should spend a reasonable amount of effort trying to test your controller. If you find yourself getting stuck, switch gears and start working on the implementation, and maybe new testing ideas will occur to you as you work through that implementation. For your own learning, keep notes of which ideas occurred to you before implementing anything, vs which ideas only occurred as a result of trying to implement the controller: is there a pattern of “things you only noticed later” that you might try to deliberately look for sooner, on future projects?
4 The Controller implementation
Design a class SameGameTextController<T>
that implements the
SameGameController<T>
interface above (also in the
cs3500.samegame.controller
package). You will need to:
Think about which additional fields and types it needs to implement the promised functionality.
Design a constructor
SameGameTextController(Readable rd, Appendable ap) throws IllegalArgumentException
. Recall from Lecture 8: Controllers and Mock Objects thatReadable
andAppendable
are two existing interfaces in Java that abstract input and output respectively. The constructor should throw theIllegalArgumentException
if and only if either of its arguments arenull
. Your controller should accept and store these objects for doing input and output. Any input coming from the user will be received via theReadable
object, and any output sent to the user should be written to theAppendable
object by way of aSameGameTextView
. Hint: Look at theReadable
andAppendable
interfaces to see how to read from and write to them. Ultimately you must figure out a way to transmit aString
to anAppendable
and read suitable data from aReadable
object. TheScanner
class will likely be useful, as will the lecture notes on controllers.Both versions of the
playGame
method should play a game. It should “run” the game in the following sequence until the game is over. Note: Each transmission described below should end with a newline.Transmit game state to the
Appendable
object exactly as the view of the model provides it.Transmit
"Remaining swaps: N"
, replacing N with the actual number of swaps left.Transmit
"Score: N"
, replacing N with the actual score.If the game is ongoing (i.e. there is more user input and the user hasn’t quit yet), obtain the next user input from the
Readable
object. A user input consists of a “move” specified by a move type followed by a sequence of values (separated by any type of whitespace):m
followed by two natural numbers.A natural number is a whole number greater than or equal to zero.
The first number is the index of row of the piece you want to select; and the second number is the index of the column of the piece you want to select. For example, an input of
m 1 3
should cause the controller to call thematch
method on your model with appropriate inputs to try and remove the match around that coordinate (see note below).s
followed by four natural numbers. The first two numbers are the index of the row and col of one piece you wish to swap. The second two numbers are the index of the row and column of the other piece you wish to swap. For example,s 1 3 4 3
should cause your controller to call theswap
method on your model to swap the pieces in those locations on the grid.
If the game is over, the method should do the following
transmit the message
"Game over."
transmit the final game state one last time
transmit the message
"Remaining swaps: N"
as beforetransmit the message
"Score: N"
as before
The method should then end.
Key points:
User input numbering: To make the inputs more user-friendly, all indices in the user provided input begin from 1. This will affect the inputs that your controller passes along to your model.
Quitting: If at any point, the next value is either the letter
'q'
or the letter'Q'
, the controller should transmit the following in order: the message"Game quit!"
, the message"State of game when quit:"
, the current game state, the message"Remaining swaps: N"
with N replaced by the remaining number of swaps and the message"Score: N"
with N replaced by the final score. The method should then end. For example:Game quit! State of game when quit: X G B X X X X X R G X X G B X Y R G B Y G R R Y R G B Y R G B Y R G B Remaining swaps: 2 Score: 5
Bad inputs: If any individual value is unexpected (i.e. something other than
'q'
,'Q'
or a number) it should wait for the user to re-enter that value again. For example, if the user is trying to swap two pieces, and has entered the first piece’s row correctly, but entered the first piece’s column incorrectly, the controller should continue attempting to read a value for the first piece’s column before moving on to read the value for the second piece’s row. The controller should behave similarly for the other commands. Once all the numbers are successfully read, if the model indicates the move is invalid, the controller should transmit a message to theAppendable
object saying"Invalid move. Try again. X"
where X is any informative message about why the move was invalid (all on one line), and resume waiting for valid input. Hint: You should probably design a helper method to retry reading inputs until you get a number or a'q'
/'Q'
. Using that helper consistently will make it much easier to implement the desired retrying behavior described here. That helper probably should not be responsible for determining if a number is a valid coordinate —that’s the model’s job — but that helper does need to return either the user’s number or their desired to quit the game. Think carefully about the signature of this method before you start implementing it... If an input is not a valid command for the game (i.e. something other than
'q'
,'Q'
,'m'
, or's'
), the controller should transmit a message to theAppendable
object saying"Invalid command. Try again. X"
where X is some helpful message (all in one line). Then the controller should try reading the next value for a command.Error handling: The
playGame
method should throw anIllegalArgumentException
if anull
model is passed to it. If theAppendable
object is unable to transmit output or theReadable
object is unable to provide inputs (for whatever reason), theplayGame
method should throw anIllegalStateException
to its caller. TheplayGame
method must not throw any other exceptions, nor should it propagate any exceptions thrown by the model.Write sufficient tests to be confident that your code is correct. Note: once the model has been tested thoroughly (which you hopefully did in the previous assignment), all that remains to be tested is whether the controller works correctly in all cases. Lecture 8: Controllers and Mock Objects will prove to be helpful.
Be sure to properly document your code with Javadoc as appropriate. Method implementations that inherit Javadoc need not provide their own unless their contract differs from the inherited documentation. Finally, no method in your implementation should exceed 50 lines. This hampers clarity of your code.
If you had to change your implementation from the previous assignment, please document your changes in a README file (a plain text file) that explains what you changed and why. This doesn’t have to be long; a simple bullet-point list will suffice. But having this documentation will make your TAs’ grading job a lot easier!
5 Testing
You will need to add additional tests to assess whether your controller works regardless of whether your model works. (Again, if you’ve sufficiently tested your model in the previous assignment, then you can rely on your model working here.) You will likely need to use the techniques in Lecture 8: Controllers and Mock Objects.
You should create your primary test class in the
cs3500.samegame
package. This test is outside your controller package,
and so can only test the
public-facing behaviors of your controller. If you want to test internal
implementation details as well, you should create one more test class in the
cs3500.samegame.controller
package, so that you can check protected and package-private
implementation details if needed.
Be mindful of which test cases you place in which test class! Technically, you could run all the tests from a single class. But using multiple classes like this helps convey to the reader of your code some of your thought processes behind each test: the reader should understand the examples first, then look at the tests of public behavior, and finally look at implementation-specific fiddly details.
Note: When you submit your full implementation, you will see automated tests that I wrote and run against your code. I gave some of my test methods mnemonic names, so that you can try to deduce what my tests are checking for. Just because I have a test for a given scenario, though, does not mean that you shouldn’t write your own test case to confirm your understanding!
6 What to submit
For your implementation: submit a properly-structured zip containing at minimum
The model interface (
SameGameModel.java
)Your implementation of the model (
FourPieceSameGame.java
)The view interface (
SameGameView.java
)Your implementation of the view (
SameGameTextView.java
)The controller interface (
SameGameController.java
)Your implementation of the controller (
SameGameTextController.java
)Any additional classes necessary to compile your code
All your tests for all your implementations in one or more JUnit test classes. You should include at least all your tests from the previous assignment, and add to them...
A brief README file (a plain text file) explaining what changes from the previous assignment you made, and why.
As with the previous assignment, please submit a zip containing only the src/
and
test/
directories with no surrounding directories, so that the
autograder recognizes your package structure. Please do not include your
output/
, out
, or .idea/
directories —
7 Grading standards
For this assignment, you will be graded on
Whether your interfaces specify all necessary operations with appropriate method signatures,
Whether your code implements the specifications (functional correctness),
the clarity of your code, including length of your methods as established in this assignment and documentation
How well your code follows the design principles discussed so far and the relevant principles in the Design Principles Masterlist,
The comprehensiveness of your test coverage, and
How well you follow the style guide.
Please submit your homework by the above deadline. Then be sure to complete your self evaluation by the second deadline.