Mini-Lab: Creating Fish in an Aquarium

This set of Mini-Lab Exercises is the first in a series in which students build a small program with several fish moving around in an aquarium. The set includes the following exercises:

• Getting Started
• Populating the Aquarium     (Concepts: Declaring, constructing, and initializing variables; providing meaningful names; reading class documentation)
• Let's Move!     (Concepts: Reading class documentation for method information; invoking methods)

Each section contains an Introduction to a problem or task, descriptions or examples of one or more Concepts to apply in solving the problem or completing the task, and an Exercise.

Before working through this Mini-Lab, students should understand the role of the main method in an application, the role of classes and objects, and the syntax for documenting code with comments.

Getting Started

Introduction

The Aquarium Simulation program is meant to simulate several fish moving in an aquarium. A skeleton of the program already exists. It contains six classes with which you will become familiar as you work through the exercises in this lab series. The skeleton program constructs an Aquarium object and a single AquaFish object; in the exercises in this Mini-Lab, you will be adding several more fish to the aquarium and directing them to move.

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 only a reference (or a potential reference) to the 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

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

public Aquarium(int width, int height)
   Constructs 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 objects of other classes may use it, 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, but we do need to provide values of the right types for the two parameters. Thus, we could construct a 600 x 400 aquarium as follows:

Aquarium myAquarium = new Aquarium(600, 400);

Exercise: Constructing Objects Read the source code for the initial version of the AquariumController class. How many constructors does it have? How many methods? What kinds of statements do you find in the constructor(s); in other words, what type of behavior is found there? What type of statements can be found in the method(s), or what type of behavior might you put there in the future? Where in the AquariumController source code is the statement that constructs an Aquarium object? Compare this with the specification for the Aquarium constructor in the Aquarium class documentation. How do you explain the differences between the class documentation specification and the actual code? Where is the code to construct the one fish in the aquarium? Does this code use one statement or two to declare the variable and initialize it to a newly constructed AquaFish object? Edit the AquariumController class to declare and construct three fish variables rather than just one. Give your new variables names that convey their purpose. Using blank lines, separate this sequence of new statements, which together perform a single function, from the existing code around them. Add or modify the comments in the AquariumController class based on your changes. Before you test your modified program, decide whether you expect this modification to change the appearance of the display or not, and, if so, how you expect it to be different. Then test the program. Was the actual result what you expected or not? If not, did you have the wrong expectation, or is the behavior of the program wrong?

Let's Move!

Introduction

Concepts: Reading Class Documentation, Invoking Methods

A method specification in the class documentation for a class 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 other objects may use them. 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 x and y are well-defined integer values, then the following are valid examples of these two methods.

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

As with constructors, you do not need to specify the type of the parameters as you pass them. Nor do you specify the return type of a 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. The runProgram method in the AquariumController class is an example of a void method.

public void runProgram()
   Runs the aquarium program.

Since runProgram 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,

controller.runProgram();