Comp 212 Lab 3: JavaDoc, Package, Immutable Lists

Create a subdirectory for this lab, say lab03, and click here to download the jar files listFWSource.jar and CLFactory.jar into this  sub directory.  listFWSource.jar contains the code for the list framework modified for the purpose of this lab only.  CLFactory.jar contains the binary class file for the CompositeListFactory discussed in the lecture.  

Extract the files from listFWSource.jar using the command:

jar -xf listFWSource.jar

1. Run the javadoc utility on the Java code by executing the command

   javadoc *.java

   Many html files will be generated.  Use a browser to view index.html.  Does the documentation include descriptions of the private fields and methods?  Now execute the command

   javadoc -private *.java

   What is the difference? How about

   javadoc -private -author *.java
   

2. Now try simply

   javadoc

   Like many UNIX commands, running the program without specifying any options will provide a brief description of its possible usage. Take a brief look at the explanation of the flags. In particular, note the -d flag for putting the documentation into a separate directory.

    

3. Remove all files generated by javadoc.  Be sure not to remove any of the java files.  We will generate the javadoc files again, after we edit and re-package the java files as prescribed in the following subsection.

1. Make IList part of a package called listFW by adding the package listFW; declaration to the top of IList.java. You need to create a subdirectory called listFW and move IList.java into it.

   Now compile using

        javac listFW/IList.java
        

   Note that you should always compile from your project's main directory. If you compile from within a package subdirectory, it doesn't find all the supporting definitions.

   We can't run anything yet, because that's just a piece of the whole program.

2. Add the package listFW; declaration to the top of IEmptyList.java and INEList.java, and move them into the listFW subdirectory. Do not make GetLength.java and TestLength.java part of the package.  GetLength.java and TestLength.java do not have a package name, and they are thus said to be in the no-name (or default) package.  

   If you try to compile GetLength.java now, you will get an error message. Try it to see what happens.

   Since GetLength makes use of IEmptyList and INEList that are in the listFW package,  you need to add the statement import listFW.*; to the top of GetLength.java to indicate to the compiler that you are using all the public classes in the listFW package. Try to compile it again.

3.  GetLength is an algorithm on IList.  We want to put it in a package that is easy to locate.  A reasonable place to put it is in a subdirectory of listFW.

   • Create a subdirectory of listFW called visitor, and move GetLength.java to this subdirectory.  The package name corresponding to this subdirectory is listFW.visitor.  

   • Add the package listFW.visitor; declaration to the top of GetLength.java.

   • In order to compile GetLength.java, you need to go back to the directory that contains listFW as a subdirectory. To avoid confusion, remove the binary class file GetLength.class  from the current directory.  Now compile GetLength.java with the command

     javac listFW/visitor/GetLength.java

4. To test GetLength, you need to have way to manufacture concrete IList objects.  The class CompositeListFactory discussed in the lecture can manufacture IEmptyList and INEList objects.  Take a look at the main method and the run method of the test program, TestLength.java.  As you can see, it makes use of CompositeListFactory to create IList objects and compute their lengths to test GetLength.  The binary class file for CompositeListFactory is bundled into the jar file CLFactory.jar that you downloaded earlier.  

   To compile your test code, type the following (Unix) command from your current lab directory:

   javac -classpath .:CLFactory.jar TestLength.java

   You should see a few error messages.  What are they?  You need to 

   • import listFW.*, to make use of all the classes for the list framework, 

   • import listFW.visitor.*, to make use of the GetLength algorithm,

     • Now, edit the file GetLength.java and add the keyword public in front of the definition class GetLength.  Without the public access specifier, GetLength is said to be package-private and can only be used  by classes inside of the listFW.visitor package.

   • import listFW.factory.*, to make use of the CompositeListFactory.

   Recompile TestLength.java. You should get no error. 

   To run your test code, type the following (Unix) command from your current lab directory:

   java -classpath .:CLFactory.jar TestLength

5. Back to javadoc!  If you feel like it, you can javadoc the java code of the above using

   javadoc -private -author listFW/*.java listFW/visitor/*.java

    

In the following exercises, assume INEList contains Integer objects only.  (Recall Integer is the wrapper class for int as discussed in class.)  Package all algorithms in listFW.visitor.

1. Write an algorithm called CheckAllNonNegative that checks to see if all elements in the host are non negative.  Its methods should return Boolean.TRUE if all the Integer elements in this host are non-negative (>= 0), Boolean.FALSE otherwise.  Write a simple test class.
2. Write an algorithm called NonNegCount  that computes and returns the number of non-negative Integer elements in the host list.  Its methods should return an Integer.  Write a simple test class.
3. Write an algorithm called Sum to compute the sum of the elements in a host list.  Write one version using direct recursion, and one version, called GetSum, using a helper alogorithm called HelpGetSum.  Write a simple test class.