PI: Laboratory 6: Communicating Applications

• Home
• Mechanics
  
  • Initial Handout
  • Syllabus
  • Learning Objectives
  • People
• Course Text
• Assignments
• Links
• Wiki

Handout 2

Note: You are on your honor not to read this handout until after you have completed the laboratory for part 1 of this assignment.

Overview

This handout describes the second part of a two-week laboratory assignment in which you will build a very simple two-player video game. In the first week's assignment, you focused on the graphical user interface (GUI). This week, you will augment that GUI so that two GUIs can talk to one another.

This assignment must be done with a partner. Part of the assignment is to be done jointly with your partner. Other parts of the assignment are to be done individually. If you do not have a partner to work with, please let the course staff know immediately.

This lab focuses on the following ideas:

• Shared state and concurrency issues.
• Communication and division of labor.
• Building communities of communities.

You should read through this entire assignment and complete the Lab preparation section before you come to lab. Some portions of the Post Lab write-up also require your thinking about them before and during the laboratory portion of the assignment. Note that this week's lab is to be designed and implemented with a partner. It is important that you plan your complete design and divide up coding responsibilities before coming to lab.

Please include the names of anyone with whom you collaborate, in any way, on this assignment. This includes your partner. (As always, you are welcome to discuss the assignment with other students in the class as well.) You should also indicate the nature of any collaborations. [Failure to include this information is a violation of the collaboration policy.]

This assignment is a two-week assignment. You should not wait until the second week to begin, however. Handout 1 covers work that you should complete prior to this week's laboratory. The complete assignment is due at 5pm on 5 November, 2003.

Contents

• Overview
• Introduction
• Pre-Lab
  • Review/Share/Explain your GUI
  • Lab Preparation
• Laboratory
  • What to Bring to Lab
  • Getting Started
  • Compiling Your Code
  • Before You Leave
• Post-Lab/Writeup

Introduction

This week, you will be extending the position panel that you wrote in last week's lab to create a very simple two-player video game. The game that you will be creating in this lab is called Cat and Mouse. You should run the demo with a partner before continuing.

Pre-Lab

The prelab for this week is a combination of last week's lab (see handout 1), a few specific exercises, and some partner preparation for this week's lab.

With your partner, you should think through the assignment and come to lab with a plan that includes at least a partial solution to the problem set and a development plan for how you intend to implement your solution. Specifically, you will need to work together with your partner to figure out how to write this week's lab and bring what you've decided (in writing) to lab with you.

Transaction Safety

[CHECK-IN, TURN-IN]

Pre-Lab Exercise 1. Design a data repository class that keeps track of an x and a y coordinate and has an additional field of type int. (The additional field might, for example, be used to hold a symbolic constant.) Make sure that your class provides transaction-safe access to its fields. It should be possible to change the coordinates (both together), but not the additional type field. It should also be possible to hand off (return, give another object) the x and y coordinates safely. (Hint: think about the SafeCoordinate class that we built in lecture.)

Pre-Lab Exercise 2. Modify your PositionPanel from last week's lab to use your safe data repository class. For this week's lab, it will be important that you build a transaction-safe version of this component, i.e., that it not be possible for the position panel to paint the mark in a place where the mouse has never been.

Questions to think about:

• How many threads can be running in your Panel extension at once?
• Might they interfere with one another? If not, explain why not. If so, explain what would happen/how you could tell.

Review/Share/Explain your GUI

You and your partner have each written a graphical user interface, a position panel. You should begin your preparation for lab by looking over one another's code. You may make helpful suggestions to one another if you see ways that your code can be improved. You should understand any differences between the code, and you should be sure that you can explain how your code might differ. At the end of this code sharing, you will want to select one version -- or construct a new shared version -- that you will use to build this week's lab. Alternately, you can each use your own version of the GUI. Bring this code with you to lab.

Either way, you should turn in your code from the first week's lab, documented and clearly marked as such, together with the complete code for your shared application. [TURN-IN]

Lab Preparation

The next stage of this project involves building a pair of networked applications. We have supplied you with the networking code, but there is still a lot to be done. You and your partners should try to design things so that each of you can write some of the code.

About the Applications

The two applications that you will write will run on two different computers and will each interact with the user as well as with the other application. One of these two applications is the Cat, and the other is the Mouse. The Mouse is a GUI application that moves a dot around its window under mouse control. The Cat also moves under the control of its own mouse, but in addition, it can see the position of the Mouse. If the user of the Cat application clicks her mouse on the Mouse's location, a "hit" should appear on both application's displays.

Setting Up a Panel

Much of the code for these two applications is the same, and most of the basic GUI infrastructure is what you built in last week's lab. In particular, both Cat and Mouse will need:

• An extended PositionPanel, i.e., a Panel that can keep track of where the mouse is. (See last week's Finger Exercises.) This Panel will also need to be able to paint several points. (See the Finger Exercises.) Note that it will not simply paint location of the mouse; you should keep these two functions somewhat separate. You will use this class later on to paint the positions of both the Cat and the Mouse, so it should be easy to change the locations of the points that are painted.
• A Frame that contains this PositionPanel. At a minimum, it should
  1. have a constructor that takes a Component as an argument.
  2. have an init method that adds the Component and handles sizing, showing.
  3. handle Event.WINDOW_DESTROY by calling this.dispose() to free up any system resources and System.exit(0) to complete execution.
• A way to establish network communication and send typed points back and forth. See the section on Making Connections with Wires, below, for further information.
• An internal representation for screen-coordinate-plus-type, so that you can send this information back and forth across the Wire. Such a representation might be used to say, for example, that "There was a hit at (109, 156)."
  • Note that you will need to agree on some types as well. The type field will be useful for sending information like "this point represents where the cat is" or "this point represents the mouse" or even "this one represents a hit". You may want to use Java constants (static final ints).
  • Since Cat and Mouse will need to agree on what the types are and what they mean, you should share the code that defines these types.
  • You can use the code that you wrote for last week's finger exercises here, but make sure that the code you write is transaction safe.
• A top-level interface to set up your application.

Each of your two applications -- Cat or Mouse -- should do the following.

1. Create an instance of the appropriate Wire. It doesn't matter which one you use for Cat and which for Mouse, but each of them should have a Wire, one generated by new ClientWire() and the other by new ServerWire().
   • You do not need to understand the particular wire classes, but you should understand the cs101.net.Wire interface.
   • You should also note that the player whose code uses the ServerWire will need to start first. (The MouseDemo uses ServerWire, the CatDemo uses ClientWire. That's why the MouseDemo had to start first.)
   • Note that these classes can send any type of Object across the network.
2. Set up an animated while(true) loop that reads data off the Wire.
3. The mouse handling code you designed earlier should output data to the Wire. (At first, send something simple like the location of the last mouseDown.)
4. Paint both points on your Panel (perhaps in different colors?) Think about which object should be responsbile for repainting the Panel, and in what sorts of situations.

You should divide up responsibility for actually implementing these pieces of code (other than the ones we've written), but you should both be involved in their design (or at least look over each other's work).

[CHECK-IN] You should bring your previous week's solutions (your position panels) and each be prepared to discuss one another's solutions and any differences between them.

Protocol for Communication

The differences between the Cat and Mouse code come in the ways that they handle mouse motion, what data they communicate over the network, and how (and what) they display. The second part of your assignment is to outline both the Cat's and the Mouse's answers to these issues. [CHECK-IN] E.g., for the Cat:

1. What data does the Cat object need to keep track of?
2. What data does the Cat object get from its GUI?
3. How does the Cat access this data?
4. What does the Cat do with this data?
5. What data does the Cat send to the Mouse?
6. What data does the Cat receive from the Mouse?
7. How does the Cat access this data?
8. What does the Cat do with this data?

The same questions can obviously be applied to the Mouse.  The two sets of answers should be consistent (which they will be if you are doing this part as a team!)

This amounts to designing an interaction protocol for the two classes. When you believe that you have a working design, you might want to try acting it out. Really! It will help visualize what is happening. Remember that you need (to simulate) one participant per thread. Agree on what things each application needs to do, and write this down for reference.

Individual Differences

Next, you should work on the implementation of Cat or Mouse (whichever one you're doing) to meet this specification.  This portion of the pre-lab should ideally be done individually, though it may be a good idea to have your partner look over your design/code draft. In lab, you will actually divide coding responsibility this way. [CHECK-IN] Among the questions that you should answer are the ones above as well as these:

1. What methods does the Cat need to have to handle the data above?
2. What data structures does it need?
3. What (if any) subordinate objects does the Cat keep track of/use to handle any of its needs? Which methods/data/services do these objects provide?
4. What threads can be (simultaneously) running in the Cat?
5. Which methods does each thread (potentially) run?
6. What data is shared across threads?
7. Where is synchronization necessary in order to ensure that your code is transaction safe? Remember that a synchronized method obtains a lock (ready-to-run license) on its containing object.

Again, the same questions apply to the Mouse.

Development Plan

The final stage of pre-lab preparation is to write up a step-by-step description of your incremental development plan. This is a collaborative activity, and you should feel free to discuss it with (or actually do it with) your partner.

The way you divide up the problems with your team members and combine your solutions will have a tremendous impact on the complexities that you encounter on the way. This is especially true of heavy-duty applications in the real world. [CHECK-IN] In particular, think about the following:

1. What is the minimum self-contained (i.e., testable) functionality that you can implement?
2. How will you test it?
3. What can you add to make a slightly more complex and still fully testable version?
4. How would you test this?

Continue listing added features and tests until you scale up to your complete design. This technique, incremental refinement, is an extremely useful and practical way to write code. You may want to read through the suggestions in the In the Lab section, below.

You probably want to test (at least parts of) your applications standalone before getting them to talk to one another. You may also want to test the network communication somewhat independently from the GUI, or at least with a relatively static or simple GUI. Your tests do not need to be symmetric, i.e., you can test a really simple Cat with a vaguely interesting Mouse, or vice versa.

Notes:

Making Connections with Wires

You will also need a way to establish network communication and send various types of points back and forth. We've provided two versions of this code, both of which implement the cs101.net.Wire interface. One is called ClientWire, and the other is ServerWire. To use these classes, you will need to download cs101.jar and put it in your classpath.

The cs101.net.Wire interface contains two methods:

public Object readObject()

This method reads an Object off of the Wire. If there is no Object to read then it will wait until the next Object is sent. Note that the return type of this method is Object; you will need to cast the Object that is returned into a more useful form. Remember that you can test to see what type of object you have using Java's instanceof operator.

public void writeObject(Object o)

This method lets you send any Object across the Wire. You can send any Object you want across the network, but you cannot send primitives (ie int).

[CHECK-IN] You can actually test the Wires without your GUI at all. For example, you can write a program that sits on one side (on one computer) and calls writeObject with a String (or even a String that includes an int that changes....use + to put a String and an int together....). The object on the other side needs to readObject() from the Wire and, e.g., System.out.println() it. You should write code for this and bring it to check-in (IN WRITING).

Laboratory

What to Bring to Lab

In addition, you should have thought out answers to all of the questions in the laboratory preparation section and should be prepared to begin writing code immediately upon entering lab. When you arrive at lab, you should have answers to the questions in the lab preparation and a copy of your code design and development plan (on-line or on paper) ready so that we can check you into lab.

[CHECK-IN] At check-in, we will specifically want to see (in writing)

• your solutions to last week's lab.
• the answers to all of the questions in the protocol for communication section.
• the code for the simple wire test described in the Making Connections with Wires section. One of you should be prepared to explain the read half, and the other the write.

You should also have prepared answers to all of the questions above, as well as a detailed development plan, and be ready to discuss them.

Getting Started

In lab, you should write and test the code that you designed.

As always, you should implement your code in simple, testable stages, building on your code only as each stage works robustly. In this case, it should be as simple as following your development plan.

A few notes:

To use the cs101.net.Wire classes, you will need to download cs101.jar and put it in your classpath.

You probably want to test (at least parts of) your applications standalone before getting them to talk to one another. You may also want to test the network communication somewhat independently from the GUI, or at least with a relatively static or simple GUI. Your tests do not need to be symmetric, i.e., you can test a really dumb Cat with a vaguely interesting Mouse, or vice versa.

Try to work through the code that you and your partner developed before lab. Remember to test small sections of your code rather than trying to type all of it in at once and then debug it. It is especially important that you become proficient at using the Wires and creating your GUI components before you try to write the full application.

Some simple things you might want to try are listed below:

• Set up a wire connection and read/write using readObject and writeObject from within the Interactions Pane.
• Start up an application that paints a red dot on the screen, and make the dot follow your mouse clicks.
• Send the dot over the Wire.

You will, of course, want to make use of your answers to the finger exercises and prelab.

Before you leave

Before you leave lab, you will need to have your work checked off by a course staff member.

At a minimum, you should expect to demonstrate two applications running on different workstations and visibly communicating somehow.

You should be prepared to answer questions about who implemented what, and about how well these implementations adhere to the previously agreed-upon specifications.

If your code does not behave as expected, you should be prepared to explain why or to describe what you have done to try to figure out why.

If your code has more than this minimal functionality, you should be able to describe and demonstrate what it does as well as how you were able to achieve this behavior.

It is always more important that you write clean, modular, well-documented and easy-to-understand code than that you go on to advanced features.

Post-Lab, AKA What To Turn In

Your completed assignment should include:

• your pre-lab assignment.
• your development plan, along with a description of how (if at all) it corresponds to what you actually did in lab.
• your code or a pointer to it, and a description of its functionality.
  • your original code, from the first week of lab, clearly marked as such. It is OK if this is revised in response to your discussion; however, this should be clearly acknowledged.
  • your complete, shared code for the two-player game.
• documentation of your code. (This can be inside the code.)
• your observations concerning
  • the coding/debugging process,
  • the behavior and reliability of your code.
  • the relationship between the interfaces that you designed and the implementations that you produced.
• the name of the staff member(s) who checked you into and out of lab each of the two weeks, a brief description of the check-out interaction, and answers to any specific issues s/he may have asked you to address.
• the names and roles of any collaborators in any parts of the project. In particular, you must specify who implemented the Cat and who the Mouse; also mention any other pieces of shared code that one of you built.
• two self-assessment checksheets. How well did you understand the first half of the lab? How well do you understand the whole lab now?

You should do your writeup individually, though of course it will be describing shared work. You may also include (pointers to) code developed by your partner, but it should be clearly marked.

This lab is due Wednesday, November 5, 2003 at 5pm.