1. Winter 2006CISC121 - Prof. McLeod1 Stuff We had better discuss a midterm date… –27 Feb. to 3 March or –6 to 10 March

2. Winter 2006CISC121 - Prof. McLeod2 Last Time Encapsulation –Private Attributes –Constructors –Mutators –Assessors –Other methods: toString equals

3. Winter 2006CISC121 - Prof. McLeod3 Today Finish up Encapsulation –compareTo –clone Javadoc Utility

4. Winter 2006CISC121 - Prof. McLeod4 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.)

5. Winter 2006CISC121 - Prof. McLeod5 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

6. Winter 2006CISC121 - Prof. McLeod6 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?

7. Winter 2006CISC121 - Prof. McLeod7 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

8. Winter 2006CISC121 - Prof. McLeod8 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.

9. Winter 2006CISC121 - Prof. McLeod9 A Complete PrimeNums Class Look at “CompletePrimeNums.java” Methods in CompletePrimeNums: –CompletePrimeNums () –CompletePrimeNums (int[]) –void setNums (int[]) –int[] getNums () –String toString () –boolean equals (Object) –int compareTo (CompletePrimeNums) –CompletePrimeNums clone () throw PrimeNumsException

10. Winter 2006CISC121 - Prof. McLeod10 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.)

11. Winter 2006CISC121 - Prof. McLeod11 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.

12. Winter 2006CISC121 - Prof. McLeod12 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 “ */ ”.

13. Winter 2006CISC121 - Prof. McLeod13 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 */

14. Winter 2006CISC121 - Prof. McLeod14 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…

15. Winter 2006CISC121 - Prof. McLeod15 Common Javadoc Tags @paramParameter_name description @throwsException_name description @returnDescription @seepackageName.ClassName, packageNamme.ClassName#methodName, etc. @author @version

16. Winter 2006CISC121 - Prof. McLeod16 Javadoc - Cont. Html tags can also be added to the comments to add more formatting to the resulting document: – for emphasis – for code font – for images – for bulleted lists –Etc…

17. Winter 2006CISC121 - Prof. McLeod17 Javadoc Reference The best reference for javadoc is at: http://java.sun.com/j2se/1.4/docs/tooldocs/javadoc/i ndex.html

18. Winter 2006CISC121 - Prof. McLeod18 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.

19. Winter 2006CISC121 - Prof. McLeod19 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.