FHTW Berlin

FHTW Berlin
Fachbereich 4
Internationale Medieninformatik
PROG1: Programmierung I
Wintersemester 03/04


Laboratory 10: Preparation for Calculator



Introduction

This assignment has two major portions. The first involves reading and understanding a substantial piece of code that we provide to you. In addition, you are expected to document this code (and to turn in your documented version with the writeup for problem set). That portion of the assignment emphasizes:

emphasizes the following topics:

You should read through this entire assignment before coming to lab. You will find it very much to your advantage to understand the code in the first portion of the assignment before coming to lab. Some portions of the Post Lab write-up for next week also require your thinking about them before and during the laboratory portion of the assignment.

As per policy, you are encouraged to discuss this assignment in detail with your classmates, but you are required to do the write-up on your own. You may get comments from other students on all portions of your write-up before turning it in, if you wish. Please include the names of anyone with whom you collaborate, in any way, on this assignment, and indicate the nature of the collaboration. [Failure to include this information is a violation of the collaboration policy.]


Written Assignment

The laboratory project for next week is a very simple four-function calculator. We have constructed the calculator's GUI (graphical user interface). Its functionality is documented in the interface Calculator (in the package calculator). Note that a Calculator is only a graphical interface; there is no intelligence connecting button presses to actions.

We have also provided you with a largely undocumented piece of code called CalculatorState. An instance of the CalculatorState class provides valuable functionality for a particular Calculator. Your assignment this week involves reading and understanding this code and writing complete documentation for it. In the lab next week, your mission will be to write the logic controller that connects the Calculator GUI with the CalculatorState smarts in appropriate ways.

Your assignment is to read through and understand the code that we have written. You will discover that the code is completely undocumented. You will demonstrate your understanding of the code to us by providing a complete set of documentation for the CalculatorState files. What you turn in should be a complete set of documentation for the code that we have written. You hand in this documentation as the pre-lab for next week's graded lab session.

You may work closely with other students to understand the code in this assignment. In fact, explaining the code to a friend is a good way to figure out whether you understand it yourself. It may also be useful to have someone read through your documentation just as you would have someone proofread your paper.

You should, however, make certain that the documentation you turn in was written entirely by you. You should also list anyone you discussed this problem set with and briefly describe the nature of your interactions.

Before you embark on your documentation of the CalculatorState class, it pays to get to know the Calculator interface.

Reviewing the Calculator Interface

You should begin by examining the Calculator interface (attached).  (You may also want to take a look at the javadoc file generated from that interface, also attached.) It defines everything that you'll need to know about a Calculator.  In particular, it contains three kinds of declarations:

ButtonIDs

The first things defined in Calculator.java are the "buttonID constants": Calculator.OP_ADD, Calculator.OP_SUB, Calculator.OP_MUL, Calculator.OP_DIV, Calculator.EQUALS, Calculator.DOT, and Calculator.CLEAR.

These are all static, i.e., accessible as parts of the Calculator interface: e.g., Calculator.OP_ADD.  They are also final, i.e., they cannot be changed.  Finally, they are all of type int

All of these constants are distinct from one another and from the numbers 0 through 9; it is intended that the numbers 0 through 9 serve as buttonIDs for their respective buttons, although they have not been given symbolic names. (In this case, 0 through 9 are actually meaningful, not arbitrary, names!)

An additional constant, Calculator.NO_OP, is not a buttonID but is provided for convenience.

Methods: getText, setText, getButton

Each Calculator object has its own getText and setText methods for interacting with the Calculator's display.  (Note that the display, and these methods, operate using Strings, not a numeric type such as int.)  Their signatures are as follows:

public String getText();
public void setText( String s);

getText() returns the String currently displayed on that Calculator's screen. Unlike getButton(), getText() doesn't wait for something to happen (e.g., for the value to change) before returning it; it just tells you what text is currently being displayed.

setText replaces any currently displayed text with its single argument, a String.

Every Calculator object also has its own getButton method:

public int getButton();

The int returned is a buttonID indicating which of the buttons was pressed: one of 0 through 9, or one of the buttonIDs defined in the Calculator interface. Each time that the getButton method is called, it returns the next button pressed. So, if the calculator's user presses 3 + 4 =, your object's first call to your Calculator's getButton() method will return 3. The next call to getButton() will return Calculator.OP_ADD. The third call will return 4, and the fourth call will return Calculator.EQUALS. Then, if you call your Calculator's getButton method again, it will wait for another button to be pressed before returning.

getButtonLabel

getButtonLabel is a method that takes a buttonID as an argument and returns a (single-character) String suitable for labeling that button. This is particularly useful if you want to print a number or operator, e.g., on the calculator's screen.

Reviewing the provided helper methods

In reading the code for CalculatorState, you should also familiarize yourself with the following method signatures.

We've provided you with a coercion routine which takes a String and returns a floating point (double) decimal number:

double cs101.util.Coerce.StringTodouble( String s );

(Remember that in Java, double (the primitive data type) and Double (the object) are two different kinds of things.)

In fact, it is built out of two java.lang.Double methods:

public static Double Double.valueOf( String s );
public double Double.doubleValue;

You can use these methods directly if you prefer.

To produce a String from a double, you can use:

public static String String.valueOf( double d );

and from an int:

public static String String.valueOf( int i );

To figure out whether a char or String appears in a given String, use

public int String.indexOf( int ch);
public int String.indexOf( String str);

The CalculatorState class

Your job is to understand and document the CalculatorState class. Note that the CalculatorState is only connected to the Calculator GUI directly through CalculatorState's constructor. The two classes have very limited interactions, mostly centering around the Calculator's display. In lab, you will add a class that provides a better connection between instances of these two classes.

Execution of this code begins when a new CalculatorState( Calculator gui ) is created. What actually happens? Continue this way through the code until you have defined all of the objects in the system. Now imagine that your CalculatorState's handleNumKey method is called. What happens then? Try calling handleOperation next, then handleNumKey again, then handleEquals. Follow through the execution of that code, too. Don't forget to write down how the various fields of objects change.

You can figure all of this out using pictures, people, or the computer. You may want to try several of these methods. Which ever approach you take, don't try to jump ahead, guessing what things will do. Instead, work slowly and carefully through the code in a step by step manner. Continue experimenting with the execution of this system of objects until you are confident that you understand how it works.

You may want to begin by drawing pictures of the various kinds of objects in this system. For example, you might take some index cards and put one object on each. Draw the first CalculatorState on an index card. List its fields and the values assigned to each. If a field refers to another object, you can write long squiggly lines to connect them, or you can be more creative. For example, I like to glue in the pointer with a piece of string or yarn. Alternately, you can simply assign each index card a unique identifier and use that to refer to the object.

Alternately, you could get together with a group of friends and play-act the changing of the objects. You may even want to do this in a classroom where there's a big blackboard for scratch work. (This idea may sound silly, but it is actually quite effective.)

What you should do

When you feel that you have an adequate understanding of what the code does and of what the various pieces of the system do, you should begin to work on your documentation.

Before Lab

Before you come to lab, you will need to have read the CalculatorState class. You may want to write an interface that describes the contract you will rely on from CalculatorState. You should in any case have a written description of

To turn in with your writeup

In addition to an understanding of what the CalculatorState class can do for you, you will need to actually go in and write documentation for this class. You do not need to bring your fully documented CalculatorState class to lab with you for checkin, but you will need this for your final writeup.

[TURN-IN next week with Report] The documentation for CalculatorState should include:

In documenting the code, you should follow the following conventions:

It should be possible to read your documentation and understand what the code is doing -- and why -- almost without reading the code itself.

You may wish to edit the code files that we have provided directly, i.e., to write your documentation as comments in the file.

Pre-Lab for next week

We recommend that you complete the finger exercises and lab preparation in cooperation with classmates. As always, a neat write-up of the finger exercises should be turned in along with your completed laboratory. If you did the Exceptions exercise the other week, this is a snap!

A. Finger exercises

You should complete the coding part of following two exercises before coming to lab next week.

A Simple Main Class

[CHECK-IN, TURN-IN] Write a class that can be used as the startup class for a program. Remember that Java's contract is that it starts at a method matching

public static void main( String[] args );

In JBuilder, the class containing this main method must be identified as the main class.

Your class's main method should do something, just to let us know it is there. You may find the cs101.util.Console class useful to accomplish this. If you want to use cs101.util.Console, you should

import cs101.util.Console;

or

import cs101.util.*;

at the top of your java file. (Otherwise you will have to refer to Console by its full name.)

[TURN-IN] Document your class, indicating what it does, how it works, and why it works the way that it does. See the style sidebars on class and method documentation for more detail.

Simple Animate Objects

[CHECK-IN, TURN-IN] Create a simple self-animating object class. The basic properties of a self-animating object are that it:

For example, instances of your animate object class might read a line from the console and write it back to the console.

You may want to use the java charts on program files and on classes as reference. Code on which you may want to build includes

To use this provided class and interface, you will probably want to import the appropriate packages or files at the top of your file.

[CHECK-IN, TURN-IN] Q. What import statements would you need to include to use AnimatorThread and Animate? How could you refer to them without an import statement?

[TURN-IN] Document your class, indicating what it does, how it works, and why it works the way that it does. See the style sidebars on class and method documentation for more detail.

 


This course is an adaption for the Fachhochschule für Technik und Wirtschaft , Berlin by Prof. Dr. Debora Weber-Wulff of a part of Prof. Dr. Lynn Andrea Stein's Rethinking CS101 project produced while she was at the MIT AI Lab belonging to the Department of Electrical Engineering and Computer Science (EECS) at the Massachusetts Institute of Technology. She is now with Franklin W. Olin College of Engineering. The copyright for all materials belongs to Lynn Andrea Stein, this adaptation is used by permission. All rights reserved.
A textbook is in preparation by Morgan Kaufmann Publishers


Questions or comments: <weberwu@fhtw-berlin.de>