Introduction

This tutorial covers:

• Java documentation style (read chapter 11 of JPL) and JavaDoc, a tool for generating documentation in html format,
• static field, static method, and the Singleton pattern to ensure uniqueness of a class's instance.

I. Java Documentation Style

The Java Development Kit (JDK) comes with a tool called JavaDoc.  This tool will generate documentation for Java source code with comments written in accordance with the Java documentation style.  The following are links to useful WEB pages on JavaDoc.

• javadoc
• writing doc comments
• Code Conventions

Create a directory ~/comp212/tutorials/02 for this lab and copy the file ~comp212/tutorials/02/*.java and the whole subdirectory ~comp212/tutorials/02/images into the new directory.  There should be 3 java source files: FunList.java, Empty.java, and Cons.java.   images contains gif files used by JavaDoc for display purpose.

Exercises:

1. Add comments to all the classes, fields, and methods in FunList.java, Cons.java, and Empty.java , a la JavaDoc.   For each class, use the @author tag and the @since tag.  For each function method, use the @return tag.  For methods and constructors that have parameters, use the @param tag.
   
2. Now you are ready to run the javadoc utility.  Execute the command: javadoc *.java.   Appropriate html files will be generated.  What are the generated html files ?  Use a browser to view them.  Are the private fields and methods displayed?
   Now execute the command: javadoc -private *.java.  Can you see the difference?
   
3. Excecute the command: javadoc.  You should see a brief description of the usage of javadoc.  Take a brief look at the explanation of the flags.

II. Singleton Pattern

Class Empty represents the "empty list".  Conceptually, there is only one empty list in this world.  The concept is akin to that of the empty set: there is only one empty set.  How can we ensure that only one instance of Empty can be created throughout the life of a program?  There is away to design a class to ensure such uniqueness property.  It is called the Singleton Design Pattern.  The following UML diagram describe the pattern.

Note that the field _instance and the method UniqueInstance () are of class scope (i.e. static).

Exercises:

1. Implement the Singleton Pattern for class Empty (solution).  Empty.UniqueInstance () now represents the unique empty list.
   
   
2. Add a second constructor

     Cons(int i)

   to the class Cons that takes a single int as an argument and creates a FunList containing that element and the empty list as its tail. This constructor should use the static method Empty.UniqueInstance ().   Since the constructor for class Empty is private, there is no way for Cons (int i) to call new Empty().

3. Add a method

     FunList append(FunList other)

   to the class FunList (and all of its variants) that returns a FunList containing the elements of this followed by elements of other. The new method must not modify this and should use the static method Empty.UniqueInstance ().

4. Create a class AppendTest with a main to test your new singleton constructor and append  method.
   
   
5. Add a method

     FunList insertInOrder(int i)

   to the class FunList (and all of its variants) that satifies the following specification. 
   Pre-condition: This FunList is sorted in non-descending order.
   Post-conditon: A FunList containing the elements of this FunList and i inserted in the approriate order is returned.
   The new method must not modify this FunList.
   

6. Create a class InOrderTest with a main to test your new insertInOrder   method.
   
   
7. Add a method FunList sort() to your class FunList class (and all of its variants) that returns a list in sorted (non-descending) order containing the same elements as this.  Hint: Use insertInOrder ().
   
   
8. Create a class SortTest with a main to test your new sort method.