CPSC 170 Lab 2: More Arrays
As usual, create a lab2 subdirectory for today's lab, open this
document in FireFox, and start emacs.
JavaDoc
In CS 120, you probably came to rely on the
Online Java
documentation when you wanted to find out the details of a certain class
You also (hopefully) learned the importance of writing good comments in the
classes that you produced.
But did you know that the two ideas are linked! It's true!
If you have good comments in your code, you can automatically generate
javadoc guides to using your classes.
Download the code Account.java to
your lab2 directory. This file contains an uncommented version
of the Account class that we wrote last semester. If you wanted to use the
account class, you would first run it through the java compiler:
javac Account.java
Think about what that does - it reads in the file and parses it
looking for recognized java commands, identifiers, literals etc. It then
translates those commands into the appropriate bytecode for the Java
Interpreter to use when running the program. For example, when it sees the
line :
public Account(double initBal, String owner, long number)
The compiler recognizes that this is a constructor (notice no return type
and the method name is the name of the class), and generate bytecode to
be invoked when trying to create an object from this class. In fact, the
compiler needs to be able to recognize all of the components of your program.
So if we have a program (the compiler) that can recognize the structural
elements of Java and translate them into another language (Java bytecode), it
is easy to imagine other programs that translate structural elements of your
program into other languages -- say HTML, for example.
This is exactly how we generate JavaDocs. Type the following at the command
prompt (make sure that you are in the directory with Account.java):
javadoc Account.java
If you look at the contents of your directory (ls), you should see that the
javadoc tool generated several files. Among them is Account.html .
Open this file in FireFox and examine the contents. What you should see is
the skeleton for a JavaDoc page for the Account class. Notice that the tool
created sections for the Constructor and each of the methods, however, the
details describing these methods are missing.
Now download the code AccountDoc.java to
your lab2 directory. This file contains an commented version
of the Account class. Open this file in emacs and observe that the comments
are only slightly different than what you learned last semester.
- A javadoc comment begins with /** and ends with */ (Note there is an
extra '*' at the beginning of the comment.
- By convention, each line of the javadoc comment begins with an '*'.
- A comment that comes immediately before the method or class name will
be used as the description for the method or class name.
- Some additional identifiers are recognized by javadoc:
- @author - can be used to identify the author of the class
- @param - used to specify the intent of input parameters. The name of the
parameter immediately follows @param and then is followed by a description.
- @returns - used to clarify the semantics of the return value.
Once you have observed how the javadoc rules have been implemented in the
AccountDoc.java file, type the following at the command line:
javadoc -author AccountDoc.java.
Note: the "-author" flag tells the javadoc utility that you want to
publish the author's name (found in the @author comment). If you do not
include this, the @author comment will be ignored.
Open the file "AccountDoc.html" and verify that the comments were used to
provide additional information about the class.
Now that you know about JavaDoc, you should start structuring your comments
to be compatible with this system. You will be required to submit a
javadoc page for all assignments in this class
Collecting Tunes
File CDCollection.java contains the code
for the CDCollection class (p.390-392). This is similar to the Accounts
Collection that we discussed in class.
File CD.java contains the code for the CD class
(p. 393-394) that CDCollection uses, and
Tunes.java contains a slightly modified version of
the Tunes class (p. 389) that uses CDCollection. Save these files to your
directory.
- Note that CDCollection is not documented in JavaDoc style. Rework this
and generate a JavaDoc Page for the CDCollection class. Make sure that you
replace the "Skeleton" comments with real ones. Notice that javadoc does not
create an entry for the "IncreaseSize" method. Why not?
- Compile and run Tunes.java. You should see a list
of 6 CDs with a total value of $97.69 and an average cost of $16.28 followed by
a menu that lets you add, search for, or remove a CD. Only the add part has
been implemented, so add a few CDs to see what happens. When you add
the 11th CD (total), you should get a message that says "Increasing size of
array" (you may have to scroll back to see it), which comes from
the increaseSize() method. This was added this just to help you follow the
program's execution.
- Now you'll add the search functionality:
-
First you need to be able to tell when two CDs are "the same." You could
compare titles and/or artists, but it's cleanest to add an equals
method to your CD class and use that.
Add method public boolean equals(CD otherCD) to the CD class, and
have it require that
both the title and the artist be the same for two CDs to be equal.
- Add the findCD method from the prelab to the CDCollection
class. Don't look through the
array any longer than you have to, and don't forget the documentation.
-
Now run Tunes again and choose the search option.
Look for some CDs that
are in the collection, some that some not, and at least one that
you added to the
original collection.
- As written, the search option in Tunes
asks for the title, artist, price, and
tracks because the CD constructor requires all four pieces of
information.
There's no need to make
the user enter the price and tracks when only the title and artist are
relevant to the search.
You
could pass dummy values to the constructor for the price and tracks,
but better yet, you could overload the constructor to the
CD class that takes
just the title and artist. Now modify the Tunes class so that it prompts for
just the title and artist
on the search function, then creates a new CD object (using the new
two-parameter constructor) and passes it to
findCD.
Test your search option thoroughly!
- Now you'll add the remove functionality. A skeleton for
a method public void removeCD(CD cd) is already in the
CDCollection class. Your job is to complete it so that
it removes the given CD from the collection if it is in there; if not,
the collection should remain unchanged.
Proceed as follows:
- When you remove a CD, you'll need to update the collection's
total cost. To find the cost of the CD you are removing you will
need to add a getCost method to the CD class. Add this method.
- To remove a CD, you first need to find it. You already have a
findCD method but it just returns a boolean, not the location
of the CD. Write a new method private int findCDIndex(CD cd)
that takes a CD and returns the index of its location in the
array, or -1 if it is not in the array. Now modify findCD so that
it just calls findCDIndex and returns false if the result is -1,
true otherwise. The body of findCD should now be just one line!
And you can use the findCDIndex in removeCD as well.
- Now you can start writing code for removeCD. First, find the
index of the CD in the array. If it is there (index != -1) you will need to "take it
out,". Remember, you can't leave an empty slot in the middle of the array -- if there
are n CDs in the collection
they should be in array locations 0..n-1, not
0..n with a hole in the middle.
- Don't forget to decrement the count.
You'll also need to add code in Tunes to get information from the user and
call removeCD when they choose the remove option.
Test the remove functionality. Be sure to try removing more than one CD, removing
a CD that is not in the collection, and mixing removes with searches and adds.
NOTE: You have added some extra methods to the CDCollection class.
This means that your javadoc file is out of date. If you have coded things
properly, you should be able to remedy this by simply rerunning javadoc.
(If you didn't add your comments along the way like you are supposed to!
you will need to go do some editing first...
Magic Squares
One interesting application of two dimensional arrays is magic squares.
A magic square is a square matrix in which the sum of every row, every column,
and both diagonals is the same. Magic squares have been studied for many
years, and there are some particularly famous magic squares. In this exercise
you will write code to determine whether a square is magic.
File Square.java contains the shell for a class that
represents a square matrix. It contains headers for a
constructor that takes the size
of the square and a scanner to read from, plus headers for
methods to read values into the square, print the square,
find the sum of a given row, find the sum of a given column,
find the sum of the main (or other) diagonal, and determine whether the square
is magic.
File SquareTest.java contains the shell for a
program that reads input for squares and tells whether each is a magic square.
Following the comments fill in the remaining code, but take it a piece
at a time as follows:
- First fill in code for
the constructor and the printSquare method in the Square class. Then
add code to SquareTest just to read and print
each square. (Note that the other methods in the Square class
have dummy return values so it will compile.)
Compile and run your program on file
magicData (you'll need to redirect the
input to do this: java SquareTest < magicData) to be sure you're reading
all 7 squares correctly.
- Now add code to compute and print the sums
of the rows and run your program again to make sure this is working correctly.
- Now add code to compute and print the sums of the columns and the sums of the
diagonals, testing as you go.
- Finally write the magic method
and indicate whether each square is magic.
You should find that the
first, second, and third squares in the input are magic, and that the
rest (fourth through seventh) are not. Note that the -1 at the bottom tells
the test program to stop reading.
HAND IN:
- Printouts of your programs - make sure that your name is included in the
header comments (not just written on)
- Tar the files in your lab2 directory with the command
tar czf lab2.tgz .