CMPE212 – Stuff… Assn 2 due next Friday. Winter 2018 Winter 2018 CMPE212 9/19/2018 CMPE212 – Stuff… Assn 2 due next Friday. Winter 2018 CMPE212 - Prof. McLeod Prof. Alan McLeod

Today Encapsulation, Cont. Look over Halloween5 again. Javadoc. WaiterData – another Encapsulation Example. Winter 2018 CMPE212 - Prof. McLeod

An Example, Cont. It would be easier to design a Class that contains (or encapsulates) these four fields and then design another class to collect instances of this Class. No way the fields could get out of sync since moving a record moves all fields at once. Collection record 1 record 2 temp array year record 3 record 4 number record 5 condition record 6 .... Winter 2018 CMPE212 - Prof. McLeod

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.) Winter 2018 CMPE212 - Prof. McLeod

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. Winter 2018 CMPE212 - Prof. McLeod

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. Winter 2018 CMPE212 - Prof. McLeod

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 (“deserialize”) the number is compared to the number stored in the class to make sure the cast will work. Winter 2018 CMPE212 - Prof. McLeod

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. Winter 2018 CMPE212 - Prof. McLeod

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…). Winter 2018 CMPE212 - Prof. McLeod

Fall 2013 CMPE212 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. Winter 2018 CMPE212 - Prof. McLeod Prof. Alan McLeod

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 2018 CMPE212 - Prof. McLeod

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 2018 CMPE212 - Prof. McLeod

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 2018 CMPE212 - Prof. McLeod

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: /** * * @param size * @return */ Winter 2018 CMPE212 - Prof. McLeod

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. * @param size The desired size of the array. * @return The array of random doubles. */ Winter 2018 CMPE212 - Prof. McLeod

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.) Winter 2018 CMPE212 - Prof. McLeod

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

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 2018 CMPE212 - Prof. McLeod

Javadoc Reference The best reference for javadoc is at: http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html Winter 2018 CMPE212 - Prof. McLeod

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 2018 CMPE212 - Prof. McLeod

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.) Winter 2018 CMPE212 - Prof. McLeod

Another Encapsulated Example The problem on the next slide – “WaiterData” - was a quiz from several years ago (written on paper!). Let’s read over the problem and then look at the solution. This solution has some extra stuff!: Javadoc comments The exception class toString, clone, equals Winter 2018 CMPE212 - Prof. McLeod

Write the code for a mutable encapsulated class called WaiterData Write the code for a mutable encapsulated class called WaiterData. This class will use the IllegalWaiter exception, but you do not have to write this exception class – you can just assume that it already exists. (Let’s write it anyways!) WaiterData is designed to hold the daily sales for a month for a particular waiter. The class will hold two attributes, a String for the name of the waiter and an array of type double for the actual daily sales values. The String must have a length of 3 or more to be legal. The array must have a size between 5 and 31 inclusive. Each individual value in the array must lie between 0 and 500 inclusive. You may assume that neither argument will ever be null. Write a two parameter constructor for WaiterData. WaiterData must have a mutator for each attribute and must throw the IllegalWaiter exception if an attempt is made to create an illegal WaiterData object or if an attempt is made to set an attribute to an illegal value through either mutator. Write accessors for both attributes. Finally, write a compareTo() method for your WaiterData class. Comparison is based on the total amount of the sales array. If the supplied WaiterData object has had a higher sales total then return -1. Return 1 if the supplied object has lower total sales and zero of both totals are equal to within a dollar. Do not write any other public methods – you do not need a toString(), clone() or an equals() method. (Let’s write them anyways!) Winter 2018 CMPE212 - Prof. McLeod