Download ppt

Stuff
• We had better discuss a midterm date…
– 27 Feb. to 3 March or
– 6 to 10 March
Winter 2006
CISC121 - Prof. McLeod
1
Last Time
• Encapsulation
– Private Attributes
– Constructors
– Mutators
– Assessors
– Other methods:
• toString
• equals
Winter 2006
CISC121 - Prof. McLeod
2
Today
• Finish up Encapsulation
– compareTo
– clone
• Javadoc Utility
Winter 2006
CISC121 - Prof. McLeod
3
compareTo() Method
• Compares a supplied PrimeNums object with the
current one, based on your comparison criteria.
• It returns an int value.
• (Like the compareTo() method in the String
class.)
Winter 2006
CISC121 - Prof. McLeod
4
compareTo() Method, Cont.
public int compareTo (CompletePrimeNums otherPrimeNums)
{
// Assume a comparison based on length of array
//only
return nums.length - otherPrimeNums.nums.length;
} // end compareTo
Winter 2006
CISC121 - Prof. McLeod
5
compareTo() Method, Cont.
• Object does not have a compareTo() method,
so we don’t have to override one.
• You could still write compareTo() as:
public int compareTo (Object o) {…}
• If instanceof returns false what do you do?
Winter 2006
CISC121 - Prof. McLeod
6
clone() Method
public CompletePrimeNums clone () {
CompletePrimeNums temp = null;
try {
temp = new CompletePrimeNums(getNums());
} catch (PrimeNumsException e) {
// do nothing!
} // end try catch
return temp;
} // end clone method
Winter 2006
CISC121 - Prof. McLeod
7
clone() Method, Cont.
• By calling getNums() we are not worried about
aliasing, since getNums() already takes care of
that.
• Do we ever have to worry about actually catching
a PrimeNumsException here?
• (The instantiation still has to be in a try/catch
block – as dictated by the merciless compiler!)
• This clone() method makes a proper, “deep”
copy of the current object.
Winter 2006
CISC121 - Prof. McLeod
8
A Complete PrimeNums Class
• Look at “CompletePrimeNums.java”
• Methods in CompletePrimeNums:
–
–
–
–
–
–
–
–
CompletePrimeNums ()
CompletePrimeNums (int[]) throw
PrimeNumsException
void setNums (int[])
int[] getNums ()
String toString ()
boolean equals (Object)
int compareTo (CompletePrimeNums)
CompletePrimeNums clone ()
Winter 2006
CISC121 - Prof. McLeod
9
Demonstrating Privacy Violations
• (in a clean way!)
• Look at “CompletePrimeNumsNoPrivacy.java”
and “TestPrimeNumsPrivacy.java” to see the
effects of privacy leaks!
• (Also contains a more sophisticated toString()
method.)
Winter 2006
CISC121 - Prof. McLeod
10
Javadoc
• Javadoc.exe is a program that comes with the
JDK. (It is in the same directory as javac.exe and
java.exe).
• If I have written a class, “MyClass.java”, that
contains properly formatted comments (more
below), then running “javadoc MyClass.java”
generates a file “MyClass.html”.
• The html file contains external documentation
generated from the formatted comments in the
source code.
Winter 2006
CISC121 - Prof. McLeod
11
Javadoc - Cont.
• Normal block comments in Java are delimited by
“/*” and “*/”. Everything between these
delimiters, usually multiple lines, is a comment.
• Javadoc block comments are delimited by “/**”
and “*/”.
Winter 2006
CISC121 - Prof. McLeod
12
Javadoc - Cont.
• The general form of a Javadoc comment:
/**
* Summary sentence.
* More general information about the
* class, attribute or method which
* follows the comment, using as many lines
* as necessary. (html tags can be included)
*
* javadoc tags to specify more specific
* information, such as parameters and
* return values for a method
*/
Winter 2006
CISC121 - Prof. McLeod
13
Javadoc - Cont.
• The general form of a Javadoc tag is:
@tagName comment
• The tags you use depend on what you are describing
(class, method or attribute).
• In the case of methods, you can have a tag for each
parameter, the return value, and a tag for each thrown
exception.
• Eclipse (really nice!!) will generate a blank tag for you after
you type “/**”.
• Typically, you will only write javadoc comments for
public attributes and methods…
Winter 2006
CISC121 - Prof. McLeod
14
Common Javadoc Tags
@param
Parameter_name description
@throws
Exception_name description
@return
Description
@see
packageName.ClassName,
packageNamme.ClassName#methodName,
etc.
@author
@version
Winter 2006
CISC121 - Prof. McLeod
15
Javadoc - Cont.
• Html tags can also be added to the comments to
add more formatting to the resulting document:
–
–
–
–
<em> for emphasis
<code> for code font
<img> for images
<ul><li> </li></ul> for bulleted lists
– Etc…
Winter 2006
CISC121 - Prof. McLeod
16
Javadoc Reference
• The best reference for javadoc is at:
http://java.sun.com/j2se/1.4/docs/tooldocs/javadoc/i
ndex.html
Winter 2006
CISC121 - Prof. McLeod
17
Javadoc - Cont.
• The output from Javadoc looks exactly like the
API documentation you have already seen - since
that is the way it has been generated!
• The advantage is that when source code is
changed, the Javadoc comments can be changed
in the source, at the same time. The external
documentation is then easily re-generated.
• Javadoc also provides a consistent look and feel
to these API documents.
Winter 2006
CISC121 - Prof. McLeod
18
Javadoc - Cont.
• Most modern IDE’s (like JBuilder and Eclipse)
allow you to run Javadoc from within the
environment, and provide tools and wizards to
help you create comments.
• For example, in Eclipse, select “Project”, then
“Generate Javadoc…”.
• See PrimeNumsJavadoc.java and the resulting
API generated by javadoc.
Winter 2006
CISC121 - Prof. McLeod
19