Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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