1. Fall 2018 CISC124
12/1/2018
CISC124
Note that the next assignment, on encapsulation, is due next Wednesday at 7pm – not Friday.
The next Quiz is not until Week 8 (this is week 6).
Fall 2018
CISC124 - Prof. McLeod
Prof. Alan McLeod

2. Today Finish Encapsulation, which includes defining:
Private Attributes
Constructors
Mutators
Accessors
toString
compareTo
equals
clone
Document the class using javadoc comments.
Fall 2018
CISC124 - Prof. McLeod

3. So Far…
We still really need a class to contain historical data about Halloween numbers, including weather conditions.
We have private attributes and two constructors.
We know how to prevent privacy leaks for mutable arguments coming in and going out of our object.
We have constructors, mutators and accessors.
And, we have defined toString and equals methods.
Fall 2018
CISC124 - Prof. McLeod

4. compareTo() Method
Compares a supplied Halloween4 object with the current one, based on your comparison criteria.
It returns an int value.
(Like the compareTo() method in the String class.)
You have to decide on the basis for comparison.
For Halloween4 you could just use numMunchkins, for example.
Fall 2018
CISC124 - Prof. McLeod

5. compareTo() Method, Cont.
The base Object class does not have this method, so you don’t have to worry about writing one to take an Object as a parameter.
Fall 2018
CISC124 - Prof. McLeod

6. clone() Method Returns a deep copy of the current object.
A “deep copy” is not aliased in any way to the original object, but contains the same values for each attribute.
See TestHalloween4.java for our object in action!
Fall 2018
CISC124 - Prof. McLeod

7. Exercises and Assignment
You are now able to work on both Exercises 8 and 9.
After we see how to implement a couple of interfaces in Halloween5 and discuss Javadoc commenting you will know what you need for assignment 3.
Fall 2018
CISC124 - Prof. McLeod

8. Halloween5
Same structure as Halloween4, but has fixed the weather mutator and implemented two interfaces:
Comparable<Halloween5> This is a generic interface that allows this object to be sorted with sort methods built into Java.
Serializable This allows this object to be saved directly to a file.
(Both of these are used in Assignment 3.)
Fall 2018
CISC124 - Prof. McLeod

9. Aside – What is an Interface?
An interface is a totally abstract class – none of the methods in the class are implemented – they don’t contain any concrete code. (Weird!)
Instead of doing something – an interface acts as a design specification and can be used as a type.
A class that implements an interface promises to have concrete versions of all the abstract methods in the interface.
More on these little beasties later.
Fall 2018
CISC124 - Prof. McLeod

10. Halloween5, Cont. See the changes in Halloween5.
See TestHalloween5.java for tests that focus on what the interface implementations allow us to do with this class that we could not do with Halloween4.
Fall 2018
CISC124 - Prof. McLeod

11. Aside – The serialVersionUID Thing
This is a unique code ID value that is used to identify your object.
Auto-generation uses various aspects of the structure of your class to generate this value. If you change the structure, you will need to re-generate this number.
It is saved with the contents of your object in the file (“serialized”).
When you read the object (“de-serialize”) the number is compared to the number stored in the class to make sure the cast will work.
Fall 2018
CISC124 - Prof. McLeod

12. Variations on a Theme…
This standard encapsulated class structure is followed by every class in Java.
Some classes don’t need all the pieces. For example:
Attributes but no mutators. (Immutable)
No attributes – then you don’t need constructors, mutators or accessors. (This class is probably just composed of utility methods, maybe all static.)
An object that will never be part of a collection – you might not need equals() or compareTo().
A class that just has a main method. This is just the starting point of a program – possibly no other methods are required.
Fall 2018
CISC124 - Prof. McLeod

13. More Variations
Of course, a class may need more methods than those we have discussed.
Think of the additional behaviour that will be useful to the user of your object.
A majority of methods should have something to do with the attributes of the object.
But you might add a few static methods if you cannot think of anywhere else to put them (the wrapper classes are like this…).
Fall 2018
CISC124 - Prof. McLeod

14. Fall 2013 CISC124
Javadoc
Javadoc.exe is a program that comes with the JDK. (It is in the same directory as javac.exe and java.exe – the “bin” folder).
It is not included in the JRE only.
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.
Fall 2018
CISC124 - Prof. McLeod
Prof. Alan McLeod

15. 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 “*/”.
Fall 2018
CISC124 - Prof. McLeod

16. 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 */
Fall 2018
CISC124 - Prof. McLeod

17. 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 the needed blank tags for you after you type “/**” above a method name.
Typically, you will only write javadoc comments for public attributes and methods…
Fall 2018
CISC124 - Prof. McLeod

18. Eclipse Javadoc Assist
For example, if you have the method header:
public static double[] generateRandomArray(int size)
Type /** right above this line and press <enter>. You will get:
/** *
size */
Fall 2018
CISC124 - Prof. McLeod

19. Eclipse Javadoc Assist, Cont.
Then you have to finish the comment:
/**
* Generates an array of random doubles. *
* The method uses the Math.random() method to generate
* an array of doubles between 0.0 and 1.0.
size The desired size of the array.
The array of random doubles. */
Fall 2018
CISC124 - Prof. McLeod

20. Eclipse Javadoc Assist, Cont.
Hold your cursor over the method header and you will get a preview of what the processed Javadoc will look like:
(Or view the Javadoc tag in the same view as the Console tag.)
Fall 2018
CISC124 - Prof. McLeod

21. Common Javadoc Tags @param Parameter_name description @throws
Exception_name description
@return
description
@see
packageName.ClassName, packageNamme.ClassName#methodName, etc.
@author
@version
Fall 2018
CISC124 - Prof. McLeod

22. 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…
Fall 2018
CISC124 - Prof. McLeod

23. Javadoc Reference The best reference for javadoc is at:
Fall 2018
CISC124 - Prof. McLeod

24. 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.
Fall 2018
CISC124 - Prof. McLeod

25. Javadoc - Cont.
Most modern IDE’s (like NetBeans and Eclipse) allow you to run Javadoc from within the environment, and provide tools and wizards to help you create comments.
In Eclipse, select “Project”, then “Generate Javadoc…”.
Let’s run javadoc on the Halloween5 class. (Note that the first time you do this, you will have to tell Eclipse where javadoc.exe resides.)
Fall 2018
CISC124 - Prof. McLeod