Iteration 8: Frameworks and MiniDraw

Deadline

Always at 23.59 on the same day as your TA session. (Except Monday classes)

Consult the deadline for your class on the delivery plan.

Learning Goals

The learning goals of this week are twofold: working on one more equivalence partitioning exercise, as well as working on frameworks. The framework aspect is dealt with in two aspects: analyzing your current HotCiv system as a framework, as well as adding a graphical user interface for HotCiv using the MiniDraw framework.

Exercise

Solve and document exercises:

And release them using the tag/branch name "Release8".

Deliveries:

  1. Documentation for your work on systematic testing and on framework analysis by following the requirements defined in the iteration 8 report template (pdf) (LaTeX source), including any backlog items you have.
  2. Create one 6-12 minute screencast that details your solution to the MiniDraw integration. Specifically, your screencast must be structured with
    1. Intro: State your names and group name
    2. Execute your 'semi' target and demonstrate "playing a bit of a round" involving unit movement, end of turn, and setting focus on a unit and on a city.
    3. Explain how your code handles unit testing for the story "A player clicks a unit, and the status panel is updated with unit information (type, owner, move count)" by running the gradle target 'setfocus' and demonstrating how the graphics is updated.
    4. Show and explain the code for the SetFocusTool, and show and explain the relevant test stub for Game used to develop and unit test the tool.
    5. Explain how your CompositionTool handles calling the proper subtools by showing and explaining the code for the tool.
    In your screencast, you should clearly indicate which of the above parts you are about to cast ("We next describe item 3: The code for our SetFocusTool looks like this, ..., and here is the stub we have used to develop it: ..." etc.).

Notes and Hints

Merge MiniDraw code into your existing code base

I strongly advice to take small steps to avoid a lot of confusion. Here is my suggestion to a good process.

  1. Do the merge in a new branch of your HotCiv, and commit after each successful step, so you have an easy time to Do Over in case things do not work out as expected. Once the merge is complete, merge the new branch back into your main development branch. I will call you own HotCiv folder structure the destination.
  2. Unzip the hotciv-framework-start (ZIP) file in some new folder (NOT in your own hotciv folder); and next test that the GUI targets in that folder are working correctly (gradle show, gradle city, gradle update, etc.). I will call you this provided GUI HotCiv folder structure the source. It may be a good idea to study the GUI/source code base and understand it before doing the merge.
  3. Merge the 'build.gradle' from the source to the destination/your own HotCiv folder. There are new targets plus new dependencies in the source build.gradle that you need in your own build.gradle. Execute 'gradle clean test' in destination to ensure your hotciv works with the new build file.
  4. Copy the source image files from folder 'src/main/resources/' into the exact same folder structure in destination/your own hotciv. Remember: gradle expects a specific folder structure, and so does Minidraw, so this copy is important. If you later experience that the graphics is not loaded, it is probably because your folder structure is wrong.
  5. Copy selected source code from the source into the destination tree. This is
    1. Copy GameObserver.java into '/hotciv/framework'. Run 'gradle test' which should still run.
    2. The folders stub, view, and visual into the same place in your production code structure.
    Now, try to 'gradle clean test' - which should give compile errors that we need to fix next.
  6. The final step is maybe a merge if you have changed the Game.java interface in any way. Copy the two new methods in Game.java (in source) into your Game.java (in destination) . The two new methods are
                    public void addObserver(GameObserver observer);
                    public void setTileFocus(Position position);
                  
  7. Adding these methods of course makes your builds fail, as the GameImpl/StandardGame you have developed is missing these methods. Just make your HotCiv compile and pass tests again by adding empty/temporary test stub methods to your own implementation. This mandatory exercise is about implementing real code for them.
  8. Everything looks good? Merge your branch back to your master.

By now, you should have all your own code compiling and passing all tests, and have all the new graphical targets executing to show graphical output with the MiniDraw based user interface.

And if you did it on a branch, merge it back to your master development branch.

Finally, IntelliJ probably does not understand the new dependency, Hit the menu item 'View' -> 'Tools Window' -> 'Gradle', click the 'Refresh' button:

Now, the MiniDraw library is available in your project, including the source code so you can actually 'Ctrl-B' on any Broker interface/class and browse the code; and the JavaDoc is also available.

MiniDraw tools and hitting stuff

The Composition tool needs to switch on the 'stuff' which is underneath to decide which tool it should delegate to: dragging a unit requires UnitMoveTool state, clicking the End of turn shield requires EndOfTurnTool state, etc. You have several options to handle that but all of them basically includes a switch 'on something' (it is a state machine, right).

The question is what 'something' is. Here are some suggestions.

  1. A very raw Gfx approach that can handle some situations, is raw coordinate inspections: For instance the EndOfTurn shield is on fixed coordinates (That you can find in class GfxConstants), so you can check that the mouse click (x,y) are within the rectangle. Have a look at java.awt.Rectangle.contains(x,y) method.
  2. Ask Drawing for the Figure underneath, drawing().findFigure(x,y). Most interesting spots to click are represented by MiniDraw figures, so if there is a figure there, you will get a non-null reference. The origin of that figure can be found using f.displayBox().getLocation(); which can be compared with the coordinates in GfxConstants.
  3. You may also use a polymorphic subclass tree for figures, and can then use instanceof to identify which figure you are clicking. Note that you end up with a lot of 'empty' subclasses (non behavioural polymorphic variation), only used to identify figure type which I generally advice against. An approach like the one I used for Tile types in Game (a 'getType()' method) is more flexible.

To handle shift-click'ing stuff: The MiniDraw tool receives the mouse event as a parameter, and you can test if the shift key is down using e.isShiftDown() (or use the MouseEvent's modifier bitmask: e.getModifiersEx() & InputEvent.SHIFT_DOWN_MASK will evaluate true in case the shift key was down during a click.)

Evaluation criteria

Your submission is evaluated against the learning goals and adherence to the submission guidelines. The grading is explained in Grading Guidelines. The TAs will use the Iteration 8 Grade sheet to evaluate your submission. The score counts towards your final grade.

Learning Goal Assessment parameters
Submission Git repository can be pulled using "Release8". Git repository is not public! Code must compile; 'gradle test jacocoTestReport' must pass, and so must the new targets ('setfocus', 'move', etc.); required artefacts (screencast and report following the template) are present.
Systematic Testing A correct EC partitioning has been made, clearly describing and arguing for the partitioning heuristics used, and documented correctly in an EC table. Coverage and representation properties have been analyzed and discussed. A correct set of test cases has been generated using proper application of Myers heuristics and are documented in a proper extended test case table. The boundary value analysis is present and correct.
Framework Analysis and Usage The framework analysis of HotCiv is correct, uses the proper terminology (hotspots, frozen spots, inversion of control, etc.), and discusses Template Method (separation and unification variant discussed). MiniDraw's hotspots are used correctly to produce the GUI for HotCiv.
MiniDraw Domain to GUI Integration The Observer pattern's subject role in the HotCiv framework code is implemented and correctly validated by JUnit test cases. The CivDrawing implementation correctly updates the GUI for all HotCiv Game state changes (demonstrated by the 'gradle update' target.) There is no Big Bang testing (see note).
MiniDraw GUI to Domain Integration Each and all of the integration tests ('gradle action', 'gradle move', 'gradle setfocus', etc.) correctly tests the required functional aspect; and uses appropriate and simple test stubs for Game. There is no Big Bang testing (see note).
MiniDraw System Test The system test ('semi' target) correctly executes a SemiCiv game with full MiniDraw GUI integration.

Big bang testing is the name of the highly problematic testing technique in which all units from many sources are assembled in one marathon system test session - in the hope that it works. Experiences are that it seldom does, and as the system is now very big and complex, it is next to impossible debug where the defect(s) are. In HotCiv, it translates into developing all the individual tools and their combination, using your full HotCiv implementation without stubs.