Reading Class Documentation and Writing Client Code

Object-oriented programs are made up of classes and objects. A class is like a blueprint for objects that you can create in the program. An object is an entity that has state (information associated with the object) and a set of operations (actions that the object can do or that can be done to the object). A program consists of objects interacting by invoking operations on each other. Some operations get information from another object, some change the state of an object, and others change the state of the outside environment. For example, in a program that simulates fish swimming in an aquarium, one operation might provide information about the location of a fish in the aquarium, another might cause a fish to move, and a third might change the way the aquarium is displayed to the user. In a program that does calculations based on data from a scientific instrument, there might be operations that look at the data, operations that archive old data and then remove them from the current set used for ongoing calculations, and operations that adjust the scientific instrument.

[Talk about the role and contents of a class vs. the role and contents of client code.]

Populating the Aquarium

Introduction

Concepts: Declare-Construct-Initialize

To create a variable for a new object in Java, you should declare the type of the new variable, construct the object, and initialize the variable to refer to the newly constructed object. Give the variable a meaningful name to make your code easier to read, understand, and maintain.

A variable associated with a class object in Java is actually a reference to the actual object. Creating the variable and associating it with an object are two separate steps. The variable declaration declares the type of object the variable will refer to, and initializes it by default to be a null reference, as in the example below.

MyClass newObject;                   // constructs reference

The variable can be assigned to refer to an existing object, or to an explicitly constructed object. A newly constructed object is initialized by a constructor method, which, in Java, always has the same name as the class. It is often possible to pass parameters to a constructor to help with the initialization. A constructor that does not require any parameters is called a default constructor. For any given class, read the class documentation to determine how to construct and initialize objects of that class.

MyClass newObject = oldObject;                // constructs new reference to existing object
MyClass newObject = new MyClass();            // constructs using default constructor; assigns to reference
MyClass newObject = new MyClass(initValue);   // constructs using one-parameter constructor; assigns to reference

It is also possible to construct both a reference and the new object to which it refers in a single line of code.

MyClass myObj = new MyClass(initValue);    // constructs and initializes both reference and new MyClass object

---

Pattern: Read the Interface for Constructors -- Abridged

You are in a situation in which you want to construct a new object. You need to know whether any initial values are needed as the object is constructed.

Therefore, read the constructor specification(s) in the class interface to determine how to construct, and initialize if necessary, the object that you need. Concentrate on the constructors that are accessible to you; for example, if you are writing client code, read the public constructor specifications.

A constructor specification will tell you

• whether the method is accessible to you
• whether you need to provide any initialization information to the constructor in the form of parameters
  • if so, how many parameters to provide
  • the order of the parameters and the type of each parameter

Reading a constructor or method specification and then writing code that meets the specification is tricky, especially for novices. This is because the client code you write will not look exactly like the specification. Think of the specification as being like a dictionary entry. Imagine that you want to use the word "cat" in a sentence, but you're not sure of its meaning. You look it up in a dictionary and find the following.

cat: noun, a small furry animal   (not the actual definition in any known dictionary!)
You would not then say "My noun: a small furry animal drank some milk." In other words, you do not use a dictionary definition by repeating it in your own writing. Rather, you use the definition to learn how to use the word being defined in an appropriate context. Similarly, you do not use a constructor or method specification by repeating it in your code. Instead, you use it to learn how to construct an object or invoke a method correctly in your code.

Let's look at an example from the Aquarium class. In this class, there is a single constructor. How do we know? A constructor specification looks like a method whose name is the same as the class. There is only one "method" called Aquarium in the class interface.

public Aquarium(int width, int height)
   Construct an Aquarium with user-specified size.
     Parameters:  width  - width of the aquarium when displayed (in pixels)
	          height - height of the aquarium when displayed (in pixels)

This specification tells us that the constructor is public, so we may use it in our client code, and that it requires two integer parameters. When we construct an Aquarium object we do not need to specify that it is public nor what the types of its parameters are, anymore than we have to specify that a cat is a noun when we use it in a sentence. We do, however, need to provide values for the two parameters. Thus, we could construct a 600 x 400 Aquarium as follows:

Aquarium myAquarium = new Aquarium(600, 400);

What if the Aquarium class also included a second constructor that took no parameters?

public Aquarium()
   Construct an Aquarium with default size.

In this case, we could use either constructor. We could construct an Aquarium with the default size (whatever that may be), with the following:

Aquarium myAquarium = new Aquarium();

Let's Move!

Introduction

Pattern: Read the Interface for Methods -- Abridged

You are in a situation in which you want an object to do something, or you want to do something to an object.

Therefore, read the method specifications in the class interface to determine how to invoke methods on the object (also known as "sending a message" to the object).

A method specification will tell you

• whether the method is accessible to you
• whether you need to provide any information to the method in the form of parameters
  • if so, how many parameters to provide
  • the order of the parameters and the type of each parameter
• whether the method will return a value to the calling method (and so can be used in larger expressions)
  • if so, the type of the return value

Let's look at two examples from the Aquarium class: width and validLoc.

public int width()
   Determine the width of the aquarium.
     Returns:  the width of the aquarium

public boolean validLoc(int xCoord, int yCoord)
   Determine whether the given coordinates specify a valid location.
     Parameters:  xCoord - x coordinate of location to be checked
  	          yCoord - y coordinate of location to be checked
     Returns:  true if specified location is within aquarium

What can we learn from these declarations? Both methods are public, so we may use them in client code. Both have return values (width returns an integer value; validLoc returns a boolean value), so we should capture the value returned in a variable or embed the method call in a larger expression. The width method does not take any parameters and returns an int. The validLoc method requires two parameters and returns a boolean value. Thus, this method may be used in a logical expression.

How can we use this knowledge? If y is a well-defined integer value (see the Declare-Construct-Initialize pattern), then the following are valid examples of these two methods.

int aquariumWidth = myAquarium.width();
if ( myAquarium.validLoc(aquariumWidth / 2, y) )
     // do something with this valid location ...

As with constructors, you do not need to specify the type of the parameters as you pass them (see the Read the Interface for Constructors pattern). Nor do you specify the return type of the method as you call it.

A method with a void return type does not return any value to the method that called it. Instead, it usually modifies its object, produces output, or changes the state of the program in some other way. It may or may not require parameters. Here is a specification of a void method from the Display class.

public void showAquarium()
   Display only the Aquarium: paint the aquarium blue to cover up old fish.

Since showAquarium does not return anything, it cannot be embedded in an expression or an assignment statement. A void method is a statement on its own. For example,

userInterface.showAquarium();