CS150 Lab7: "Pop" Goes the Design

Due Sunday 11:59 PM 11/12/00

This week's lab will be the software design of a computer model of a soda machine. There is no actual Java coding for this lab!

Now's the time to finally get the answer to the question "where do objects come from". Oh sure, we could give you the Constructor and the Bees story again -- but I'm sure you want to know more. For example, how do you decide what classes you will need for your application? The biggest warning I can give you for this project is don't start to program too early. During this project we will be creating a pop machine (or for you New Yorkers a soda machine). Initially you can picture a machine that just dispenses cans of pop, all of which have the same price. It only accepts and returns coins. Later, you will add in the ability to handle multiple prices.

You will work in groups of 3-4, but hand in individual write-ups. Be sure to put your team members' names in the write-up. It is expected that to some large degree, the individual write-ups in a group will be similar, but do not hand in multiple copies of the same file. It is important to use your own words as much as possible so that the ideas make maximal sense to you personally. Work in a group, getting everything done and written, then finish off your work such that it makes the most sense to you .

This is the basic process you will go through to create your design:

Create a mission statement (Word document) -- what are you trying to do?
Create a detailed narrative (Word document)-- Explicit details about the system to be modeled.
Create a UML Use Case diagram (Structure Builder) -- Detail the interactions, tasks and subtasks.
Create CRC cards (3"x5" cards) -- What possible classes might be needed, and what do they need to do and with what other classes do they interact?
Add the CRC card info to the Use Case diagram (StructureBuilder).
Create UML Class diagram and class stubs (StructureBuilder) -- What are the relationships between the classes? No method bodies!!
Perform test case analysis (Word document) -- Does it work? Rework Use Cases, CRC cards and class diagram if necessary.

Group Formation

Quickly form a group of three or four students (no more than 4 and no less than 3!). This week's lab benefits from interaction with other people. Choose people with whom you might be able to meet outside of class if you need the time.
Select a name for your group and create a logo for it if you wish -- be proud of yourselves!.

Design constraints:

Your job is to create a software model of a real soda machine, that is, the program must simulate the behavior of a real soda machine. One of the questions you will have to answer to yourselves is to what extent your code needs to accurately model the internal workings of a real soda machine.

Your soda machine design will be done in two stages with the following constraints:

Section 1: Takes coins only, unlimited change-making capability, many different kinds of soda, all same price.
Section 2: Takes coins only, unlimited change-making capability, many different kinds of soda, various prices.

Lab Sections

Create a lab directory as you normally do, with two sections. Each section, place
1. The MS Word document described below.
2. A StructureBuilder project for that section with
  1. A Use Case diagram.
  2. A UML diagram.
3. All Java files created by StructureBuilder for your UML diagram.
4. A "DOCS" subdirectory, in which the documentation web site for the Use Case and UML diagrams created by StructureBuilder for the section are placed. See the instructions on how to create Javadocs using SB.
Place any Java code created in its own package directory. If you have any classes that are the same name but are different for the two sections, call them something like "Class1" and "Class2" so they can be distinguished.

Use Cases

Create Use Cases ("Real Use Cases" and "Essential Use Cases" -- see definitions below) According to Larman, a "use case is a narrative document that describes the sequence of events of an actor (an external agent) using a system to complete a process. They are stories or cases of using a system. Use cases are not exactly requirements or functional specifications, but they illustrate and imply requirements in the stories they tell." [Larman: "Applying UML and Patterns," Prentice Hall] An actor is usually an entity that is outside the system who stimulates the system with input events or receives something from the system. The program's user is an actor for instance. A use case thus describes some task that the actor wants the system to accomplish. A single program may have many use cases for the different things it is trying to accomplish.

REMEMBER: USE CASES ARE IMPLEMENTATION INDEPENDENT!

Stay far, far away from anything that even smells of Java code when writing use cases.

See the Java Resources page on Use Cases

We will use StructureBuilder's Use Case diagramming capability to create diagrams that model the behavior of a system in response to interactions with external agents ("actors"). In other words, a use case diagram shows the actors and the tasks they may want to accomplish with system (use cases). Follow the formatting as shown in the Use Case example diagram.

Common mistakes are to get too technical at this point and start programming. Try to stay focussed on creating an essential-type use cases. It is hard to know what the granularity of use cases should be. You may want to write several versions of the same use case, but at different granularity levels. Try to think of the use cases in terms of "is a" (generalizations) and "has a" (dependencies such as includes and extends) type relationships.

Definitions:

Essential Use Cases

These are the abstract behaviors of the system, and are implementation independent. These describe the "essential" or fundamental behaviors of the system. "Takes money and returns product if enough money inserted" would be an example of an abstract behavior described by an essential use case.

Real Use Cases

These are concrete physical implementation behaviors of the system that involve specific capabilities that are available. "Takes quarters, dimes or nickels and places a can in the output chute if enough money is inserted" would be an example of a concrete behavior described by an real use case. A real use case will appear as a "sub-case" of an essential use case. That is, there will be a generalization arrow (solid line & head) pointing from the real use case to the essential use case. Notice that there is still no reference to code implementations.

CRC cards

After you are done creating your use cases, you will need to develop CRC (Class/Responsibility/Collaborator) Cards. Choose a use case and follow it through from beginning to end. When the system has to respond, create a class (or use an existing class) to handle that responsibility.

A person in your group should take a 3 x 5 index card and write the name of the class across the top. Then make two columns, one for Responsibilities and one for Collaborators. As an example (you would never have this in your pop machine), say one of the types of pop has run out. You might then decide that the PopStocker class has the responsibility of contacting the PopDistributer class to request more of that type. (let's be clear -- your pop machine shouldn't have either of those classes).

After a while different people in your group should be holding different class cards. You can then track a use case by seeing which class sends what messages to other classes and what the response should be.

These are 3 x 5 cards for a couple of reasons. First, they are small so you should have no classes that do too much. Second, they are inexpensive so you should have no trouble ripping up a class that you no longer need. This is the place where you can create and discard classes with little or no penalty.

Create "collaborations" in your use case diagram and insert your CRC card descriptions as the documentation for the appropriate collaborations. Note that a single collaboration may contain the CRC cards of several classes. You will need to change your columns into sections with neatly and clearly formatted sections.
NO JAVA CODE ALLOWED ANYWHERE!! However, do note that if done properly, the necessary code should be painfully obvious.

MS WORD DOCUMENT SPECIFICATIONS

Put your name plus all the names of your teammates in your Word document!

Your Word documentation should contain the following sections.

The Mission Statement

Write a brief statement that explains what your goal is in this project. Keep your statement simple, clear and focussed. This is a quick overview statement.

Your mission statement may change as the process evolves. Its purpose is to be a standard against which you can measure what you are doing. One person may suggest that your pop machine open the can and pour it into a cup which has ice in it -- you can then point to your mission statement and remind yourself that that isn't what you are creating.

The Descriptive Narrative

Write a descriptive narrative. Now you are trying to completely describe what your pop machine is and does. It is useful to describe it in terms of how people interact with it. You should include references to your customers and the goals of the project as well.

This is one possible first step in finding your classes (but not one that we are using today). This technique consists of going through your nouns in the descriptive narrative for a suggestion of classes and looking at verbs for methods.

Test Cases

Now that you think you have the classes chosen and everything thought of -- run them through a test suite. What happens when you deposit a quarter?... What happens when you try to make a selection and you have deposited too much money?... Not enough money?...

Suggest other test cases and run them on your design.

Your test suite must include at least the following scenarios, assuming the Coke and Sprite both cost $0.55:

Section 1 and 2:

The user inserts a quarter and pushes the Coke button.
The user inserts two quarters and a dime and then pushes the Sprite button. Be sure to clearly identify what processes cause the correct product to be dispensed.
User pushes the Coke button without inserting any money.
User inserts two dimes, two nickels and one quarter, then pushes the coin return button.

Section 2 only:

User inserts two quarters and three dimes and presses the Orange Juice ($0.75) button (i.e. not the Coke button and a different price). Be sure to clearly explain why the correct product is dispensed at the correct price.

The level of detail you now want to achieve:

What method(s) is(are) being called.
What that method is supposed to do.
What properties that method uses to accomplish its task.
What other methods that method calls to accomplish its task.
What those other methods do, use and call.

For Section 2 Only

What needed to change now that your machine dispenses beverages that aren't all the same price? Why did you have to make those changes, that is, how did those changes enable your soda machine to have its new functionality?

What other changes might you suggest that your machine be able to change in the future?

UML Diagram

You can now take your CRC cards and represent them in a UML diagram. You are creating the stubs that you will need to write a pop machine program. You are not writing the actual code for the methods!

When you create classes in SB, be sure that the files get saved to the appropriate directory!

Inside StructureBuilder, fully comment all the classes, methods (including their input parameters) and properties. Your comments should describe what the class, method, or property does , not just what it is (the name alone should do that).
Use SB's "Generate Documentation" feature, under the "Tools" menu, to create a mini-web site in the "DOCS" subdirectory in the appropriate lab section directory.
Generate documentation for your use case diagram as well.

Use SB's "Export Image" feature to create a "PNG" graphic image files that can be imported into your Word document.