MP3: Refactoring and More JSON

To start working on Checkpoint 3, follow these steps:

A new run configuration called Test Checkpoint 3 will run the Checkpoint 3 test suite. If you run into a problem obtaining MP3, please get help immediately.

Because the new test suite refers to a class that you need to add, your project will not be able to compile immediately after applying the patch. This will be fixed as you start working on the checkpoint as described in Your Goal.

Like in previous checkpoints, setting useProvided in grade.yaml to true causes the app to use our provided components rather than your implementations. For Checkpoint 3, we provide TargetVisitChecker (with both MP0-style and refactored signatures), AreaDivider, the launch activity, the main activity, the local game setup UI in NewGameActivity, and the gameplay logic in GameActivity.

If you didn’t finish the game setup activity in MP1, you can still do MP3. Our provided components will try to fuse the game setup UI you have with our version of the missing parts. However, it would be ideal to get testSetupUI from MP1 done as soon as possible so that you can set useProvided back to false. If you’re curious about how the installation of provided components works, you can post on the forum.

As usual, you can always go back and make submissions to previous checkpoints by changing checkpoint in grade.yaml.

Java arrays are useful for storing multiple values of the same type, but an array’s length cannot be changed after its creation. Often it’s not known in advance how many entries a collection will have, or the collection has items added to or removed from it. In those situations, arrays are inconvenient.

Fortunately, Java provides lists: objects that hold dynamically resizable lists of things. All lists are instances of List, but List is an interface rather than a concrete type. To create a list you create an instance of a List implementation, the most common of which is ArrayList. This is an example of polymorphism.

When you declared arrays, you put the element type before square brackets, like String[] for an array of strings. List variables are declared like List<String>, with the element type in angle brackets. To declare a list-of-strings variable and initialize it to an empty ArrayList, you would use code like this:

The angle brackets on the right side of the assignment can be empty, which means that the actual list object created holds the same type of values as the variable is declared to contain.

The List type defines many functions that are usable on all lists. The most useful ones are:

For example:

Lists can be iterated over with the enhanced for loop:

Types like List and ArrayList will need to be imported before you can use them. Android Studio can help with this: if you press Tab to autocomplete a type name, any needed import statement will automatically be added at the top of the file.

Dropdown lists are useful when the user has a handful of possible choices. Android provides a Spinner control in the Containers tab of the Palette that produces a dropdown list. It is possible to populate the dropdown dynamically at runtime, but it is much easier to set the entries attribute in the Attributes pane to a string array resource. Then each string in that array resource will be one entry in the dropdown.

Some useful methods of Spinners:

If you’d like more information, you can see Android’s guide to spinners.

In Checkpoint 2, you used Gson to read data from parsed JSON. In this checkpoint, you’ll need to create JSON objects to send to the server.

Gson can help with this too. To create a new JSON object, use new JsonObject(). To add a single, simple value like a string or number as a property on an object, call the object’s addProperty function, passing the property name and value. For example, this code builds a JsonObject corresponding to the first MP2 JSON example:

To add a more complicated value like an array or other object as a property of an object, use add instead.

Likewise, to create a JSON array, use new JsonArray(). Its add function will add an entry to the end of the array.

This code reconstitutes the more complicated JSON object from the MP2 writeup:

Gson objects stringify to the JSON text they represent, so you can pass them to System.out.println to see what JSON you’ve built. It will be condensed onto one line and difficult to read, so you may find it helpful to paste that into a JSON formatter to see its structure more easily.

To create a multiplayer game, your app will need to make a POST request to the /games/create endpoint. Since there is a lot of game information rather than just a game ID, the game configuration will need to be uploaded to the server as the body (payload) of the request. The body should be a JSON object (Gson JsonObject instance) with these properties:

You may find the example target mode body and example area mode body helpful.

If the game is created successfully, the server’s response will be a JSON object with a single game property whose value is the (string) game ID.

If the game cannot be created, your error handler will be run. The getMessage function on the error object returns a human-readable string describing the problem.

If you are attempting the extra credit feature to allow the user to load a predefined set of targets, your app will need to be able to fetch the preset targets lists from the server. Those are accessible by a GET request to the /presets endpoint. The server’s response will be a JSON object containing this property:

You may find this example response helpful. Do not assume that the note property will always be present on target objects, but feel free to do anything you like with it if it’s there. You can always ignore it completely.

Version control systems like Git make it possible to retrieve older versions of your code, which is very useful if you accidentally damage a file. Android Studio integrates with Git to allow you to undo (revert) changes with its UI.

If you would like to put a file back to how it was at the last commit, right-click it in the Project pane and choose Git | Revert. This brings up the Revert Changes dialog, where you can select any additional files you would like to revert. Reverting a file throws away all changes to it since the last commit and is usually not reversible.

For a more surgical approach, Android Studio highlights changed regions of files with colored bars or gray triangles in the left margin of the code editor. Clicking one of these decorations produces a toolbar with a back arrow (Rollback Lines) button that reverts just the highlighted lines to how they were in the last commit. This rollback method may sometimes be reversible with Ctrl+Z, but you should still be certain that you want to throw away your changes.

The new test suite, Checkpoint3Test, is initially unable to compile because it refers to a Target class which does not exist, so this must be fixed first. We will be using the Target class primarily in the next checkpoint to help manage a target marker on the map, since the Checkpoint 0 approach of passing coordinates to a changeMarkerColor function is unwieldy 2.

Create the class by right-clicking the package containing all your other Java source files, choosing New | Java Class, entering Target in the Name field, and clicking OK.

To see the needed public members of this class, refer to our official Javadoc. You will need to store a Google Maps Marker object in a private instance variable.

To place a marker on a Google map, use the map’s addMarker function 3:

To change the color of a marker after it has been created, use its setIcon function 4:

After completing this task, testTargetClass will pass. You may optionally rework your target mode logic in GameActivity to take advantage of this new class, but otherwise you will not need it again in this checkpoint.

Functions that take eight parameters, especially all of the same type, can be difficult to use. This is even more unfortunate when some of the parameters really belong together, packaged up into objects. Now that you know how to use objects like the Google Maps SDK’s LatLng, we’ve rewritten LinesCrossDetector.linesCross to accept the lines' endpoints as LatLng objects. 5

Download the LineCrossDetector patch and apply it with VCS | Apply Patch like you do with the checkpoint patches. This will introduce compilation errors in your functions that use linesCross! You need to adjust those to use the improved version’s signature, calling it with four LatLng positions.

Similarly refactor the addLine function in GameActivity to take two LatLng endpoints rather than four double coordinates. You will need to update the function’s callers to be compatible with its new signature.

If you make a mistake while refactoring and want to put a file back to how it was at the last commit, see the section on reverting changes.

After completing these tasks, testLatLngRefactor will pass.

In Checkpoint 1 you made it possible for the user to select the area for area mode by panning and zooming a Google Maps control. Now you’ll add a similar map control that allows the user to choose the targets for a target mode game by pressing to add a target and clicking a target to remove it.

To add another map to the game setup activity, open activity_new_game.xml in the UI designer, copy the areaSizeMap fragment, paste it inside the target mode settings layout 6, and change the copy’s ID to targetsMap.

In NewGameActivity's onCreate we provided this chunk of code:

This gets a reference to the areaSizeMap fragment and registers a handler that will be run when Google Maps creates the map. When the map is available (in getMapAsync), it is stored in the instance variable areaMap and passed to our centerMap function for centering on Campustown.

Declare another instance variable to store the targets map, then duplicate the above section of code to similarly prepare your targetsMap fragment. Make sure to change the findFragmentById parameter to operate on your new fragment. You’ll then be able to see in the app that the map that appears for target mode setup is centered on Campustown just like the area mode setup one.

To keep track of the targets added so far, declare an instance variable to hold a list of Google Maps markers: a List<Marker>. Initialize it to a new, empty list. Add some code to your new getMapAsync handler to make the user’s actions on the map add targets:

In summary, you’ll want code like this inside the new getMapAsync:

After completing this task, testTargetMap will pass.

When setting up a game, the user should be able to decide who is invited to the game and what roles they have. An invitee can be added by entering their email into a text box and pressing the Add button. All players (users involved in or invited to the game, including the app’s user), should be shown in a list with a dropdown to set the role, which defaults to observer. It should be possible to remove an invitee—but not the user—by pressing the Remove button in their row.

To make this possible, we will need three new UI elements in activity_new_game.xml:

To display one player entry, we have provided chunk_invitee.xml in the patch. You do not need to modify it, though you may customize it if you like. To store information about one player, we have provided the Invitee class. These will be used in NewGameActivity to make the invitees UI work.

Add an instance variable to NewGameActivity to store the list of players, that is, a List<Invitee>. onCreate should initialize it to an empty list and then add an Invitee representing the user with the role of observer. You should create two helper functions to make the players list UI work:

The targets map and invitees UI can be done in either order. Once they’re both ready, the data they solicit from the user can be submitted to the server to create a multiplayer game.

When the Create Game button is clicked, build a JsonObject according to our API documentation for the game creation endpoint. You will need to include:

Much of your Checkpoint 1 logic can still be used; you’re just putting the data in a JSON object rather than an intent.

When your game JSON object is ready, POST it to the game creation endpoint. If the request succeeds, launch GameActivity passing the game ID from the response as the game extra of the intent, then finish NewGameActivity. If the request fails, show a toast (like in the example web request's error "handler") that displays the error’s message 7 so the user knows what went wrong.

Note that GameActivity should only be launched once the request completes, not immediately when the user presses the button. The Checkpoint 1 data no longer needs to go in the intent, though you can put it there if you’d like the game to keep working in the meantime before Checkpoint 4 fixes everything.

After completing this task, testApiRequest will pass. Nice work! If you’re up for a challenge, you can continue on to the extra credit section below.

Challenge problem! This is extra credit because it takes a bit more work and tinkering. It can be done before the game creation API request, but you will need to have the targets map working first.

Many users won’t want to spend a lot of time picking out enough targets for an interesting target mode game. To make it easier to add a set of targets, the app could have several suggested lists of targets and allow the user to add an entire suggested list at once.

Inside the target mode settings group, add a button with text "Load Preset" and ID loadPresetTargets. When it is clicked, fetch the list of presets from the server. When the request completes, create and show an AlertDialog to list the options. Refer to Android’s AlertDialog guide for details.

This patch provides a chunk_presets_list.xml layout resource which you can inflate with a null parent 8 and pass to the dialog builder’s setView function. For each preset option, add a RadioButton inside the provided RadioGroup (ID presetOptions), with the radio button’s text set to the preset’s name. This is the one place in the MP where you should create an individual view dynamically using new. The constructors for most Android views take a context, which can be the activity: this.

The alert dialog’s positive button should be labeled "Load"; its negative button should be labeled "Cancel." The dialog might look like this:

If the positive button (Load) is pressed with a preset selected, all existing targets should be removed and all the targets from the selected preset should be added. There are multiple ways to associate a preset with a radio button; you may find getTag and setTag helpful. If the user presses Cancel or presses Load without selecting a preset, do nothing and the dialog will be dismissed by default.

If you complete this task, testTargetPresets_extraCredit will pass and you’ll have earned 20% extra credit!